atlassian-marketplace-mcp

Server Quality Checklist

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

Latest release: v0.3.2
Disambiguation4/5
Most tools have distinct purposes, but the large number (95) and a few aliases (e.g., transactions_aggregate_by_hosting) create minor ambiguity. Overall, the tool set is well-organized, but some reporting tools could be confused without careful reading of descriptions.
Naming Consistency4/5
The naming convention is predominantly underscore_case with a resource_action pattern (e.g., app_listing_get, developer_space_member_add). However, there are deviations like 'apps_known' and 'free_starter_tier_export' that break the pattern, and some tools use 'by' in the middle. Overall, it's fairly consistent.
Tool Count2/5
With 95 tools, the server is extremely large. While it covers many endpoints, the typical well-scoped server has 3-15 tools. This sheer number makes it difficult for an agent to navigate and select the right tool, even with good descriptions.
Completeness3/5
The tool set covers major areas like app listing, app software, versions, developers, promotions, and reporting. However, notable CRUD operations are missing: there is no delete tool for app listings, app software, versions, or tokens. This leaves gaps that could cause agent failures in lifecycle management.
Average 4/5 across 95 of 95 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 5 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under 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

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and not readOnly. The description adds 'full replace' which reinforces destructive nature but does not disclose additional behaviors like required permissions, side effects, or success/failure modes. 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?
The description is concise at one sentence plus a link, but it lacks structure; it does not front-load key details beyond the core action. Adequate but not exemplary.
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, no param descriptions, and a complex resource with nested body, the description is insufficient. It does not explain what the body should contain, the meaning of version, or response details. The spec link partially mitigates but the description itself is incomplete.
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?
Input schema has 3 required params (appSoftwareId, buildNumber, body) with 0% description coverage. The description does not explain any parameter semantics, leaving the agent to infer from the link or name alone. This is a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates one version of an app-software with a full replace (PUT). The verb 'update' and resource 'app-software version' are specific, and the 'full replace' distinction differentiates it from create or get siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like create or get. The description only states the HTTP method and full replace nature, without any context on prerequisites or when to prefer this over other operations.
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 mention of 'full replace' and 'PUBLIC IMPACT' adds some context about customer-facing changes and the replacement behavior. But it still lacks details on permissions, reversibility, or error states, which is acceptable given the annotations cover the basic destructive trait.
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 second sentence is a long URL, which reduces conciseness. The information is front-loaded with the action and impact, but the length could be trimmed by shortening the link or integrating it as a reference.
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 three required parameters, a nested object body, and no output schema, the description should explain return values, prerequisites (e.g., existing listing), and body structure. It only mentions 'full replace' and customer-facing impact, leaving 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.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has no descriptions (0% coverage), and the description does not explain the 'body' parameter's structure or the meaning of 'appSoftwareId' and 'buildNumber'. While the spec link provides external documentation, the description itself adds minimal 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 'Update an existing version-listing (PUT — full replace)', specifying the verb, resource, HTTP method, and replacement semantics. However, it does not differentiate from sibling tools like app_listing_update or app_version_listing_create, which could be confused for similar operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes 'PUBLIC IMPACT: changes the customer-facing version metadata after approval', providing some context on when the tool should be used (after approval). However, it offers no guidance on when not to use it or alternatives (e.g., app_version_listing_create for new listings, app_listing_update for app-level updates).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description's mention of eventual public impact adds moderate context. However, it does not elaborate on immediate behavioral effects, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences plus a spec link). The first sentence front-loads the purpose, and the second adds relevant workflow context. Minor: the spec link could be omitted if not actionable.
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 creation tool with a complex body parameter and no output schema, the description is insufficient. It does not explain the structure of the 'body' payload or list constraints. The agent would need external documentation to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'body' has a description, 'appSoftwareId' lacks one). The description does not compensate by explaining parameters or providing examples. The free-form 'body' object is left completely underspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a new version') and the resource ('for an app-software'), distinguishing it from sibling tools like get, list, and update. The mention of 'PUBLIC IMPACT' adds context but is not essential for 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 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 its siblings (e.g., update, get). There is no mention of prerequisites, alternatives, or exclusions, leaving the agent to infer usage from the tool name alone.
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, destructiveHint=false, and idempotentHint=true, so the description's safety profile is well-covered. The description adds the list of returned fields (name, size, content type, download URL), which provides useful behavioral context beyond annotations. However, it does not disclose other traits like pagination, rate limits, or data 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 extremely concise: a single sentence that conveys the tool's purpose and key returned fields, followed by a reference link. There is no wasted text, and every word contributes value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, no output schema), the description is partially complete. It lists the returned metadata fields, which helps the agent understand what to expect. However, it omits parameter explanation and does not leverage the sibling context to guide tool selection, leaving a notable gap in completeness.
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 the parameter 'artifactId' at all. The input schema has 0% description coverage, so the description carries full burden. It fails to explain what the parameter represents, its format, or constraints, leaving the agent without meaningful semantic guidance.
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 it retrieves artifact metadata and lists example fields (name, size, content type, download URL). It uses a specific verb 'Get' and resource 'artifact metadata', but does not explicitly differentiate from the sibling tool 'artifact_fetch_from_url', which likely fetches the actual file content rather than metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when not to use it, or how it compares to similar tools like 'artifact_fetch_from_url'. The agent is left to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The destructiveHint annotation already signals a destructive operation. The description adds minimal context: it specifies 'unused' but does not explain behavior if the code is already used, effects on related data, or whether deletion is irreversible. It relies heavily on 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 a single sentence and a link, which is concise and front-loaded. However, the link may not be actionable by the agent. It is efficient but could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with two required parameters and no output schema, the description is incomplete. It lacks information on return values, error conditions (e.g., code already used), and any prerequisites like partnerId that might be needed. The link partially compensates but is not fully integrated.
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 promotionCode has a description. The description does not add meaning for promotionId and does not elaborate on the format or constraints of either parameter, leaving the agent to infer 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 uses the verb 'Delete' and specifies the resource as 'unused single-use code', clearly indicating the action and scope. It distinguishes from sibling tools like promotions_code_get and promotions_codes_list by narrowing to deletion of unused single-use codes.
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 code is already used or for batch deletion. 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 readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds 'aggregated sales' and references an endpoint, but does not disclose behavioral details like pagination, filtering limits, or data freshness beyond what the 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences and a URL, avoiding unnecessary verbosity. However, it could be structured to include parameter context or return type hints without adding length. The front-loading is 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 no output schema, the description should hint at the return format (e.g., grouped counts or time-series). It does not. With 6 parameters and moderate schema coverage, the description is incomplete for full understanding. Annotations cover safety but not usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (3 of 6 parameters have descriptions in the schema). The description itself does not explain any parameters beyond the metric path segment, failing to clarify the semantics of startDate, endDate, hosting, or the aggregation granularity. This leaves ambiguity for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns 'aggregated sales grouped by a metric path segment' and maps to a specific endpoint. It indicates the resource and verb but does not explicitly differentiate from sibling tools like 'transactions_aggregate_by_hosting' or other metrics-related aggregates, though the metric parameter provides some distinction.
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. There is no mention of prerequisites, context for grouping by metric, or when not to use it. Sibling tools exist with similar aggregation patterns, but the description provides no direction on 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?
Adds significant behavioral context beyond annotations: warns that token identifiers and customer cloud sites are exposed ('CREDENTIAL-ADJACENT'). Annotations already declare readOnlyHint=true, destructiveHint=false. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences including a warning and spec link. Front-loaded with purpose. Could be more concise; the spec link is helpful but adds length.
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 purpose, return format, and sensitivity. Leaves gaps: no mention of pagination, error cases, or required permissions. With no output schema, the return format description helps but is incomplete regarding edge cases.
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% (appSoftwareId has no description). The description does not elaborate on appSoftwareId parameter. The token parameter is explained in schema but not mentioned in description. Fails to compensate for missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'List API access tokens minted for this app-software' with specific verb+resource. Return format is given. Distinguishes from sibling 'app_software_token_create' which creates tokens. However, does not explicitly state it is a read-only operation (though annotations cover that).
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 (e.g., app_software_token_create). No mention of prerequisites or conditions. The spec link provides reference but not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive (destructiveHint true). Description adds that it's a 'full replace', which clarifies overwrite behavior beyond annotation hints.
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?
Very short: one sentence plus link. Front-loaded purpose but missing key details. Link may not be actionable for agents.
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, nested objects, and 0% schema coverage, description is incomplete. Lacks details on request body structure, response, error conditions, and authentication requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. Description does not explain any parameters, including the 'body' object or identifiers. Relies solely on external spec link, which is insufficient for agent decision-making.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Update' and resource 'developer-space team member', and specifies it's a full replace via PUT. Distinguishes from sibling tools like add, get, remove, list.
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 vs. alternatives like add or remove. Does not mention prerequisites or edge 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 indicate destructiveHint=true and readOnlyHint=false. The description adds 'AFFECTS OTHERS: revokes their console access,' providing behavioral context beyond annotations. 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?
Two sentences plus a link, no fluff. The key action and behavioral warning are front-loaded. The link provides extra detail without cluttering.
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 must cover inputs and consequences. It covers the action and a behavioral warning but fails to describe parameter roles or the overall response. Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage. The description does not explain the parameters 'aaid' or 'developerId'. The link to spec might help, but the description itself adds no 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 states 'Remove a user from the developer space' which is a specific verb+resource. The added 'AFFECTS OTHERS: revokes their console access' clarifies scope. This distinguishes it from sibling tools like add, get, list, update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. The description implies usage for removal but does not mention alternatives or prerequisites. The 'AFFECTS OTHERS' note hints at impact but not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds only 'Poll status', which aligns with readOnly. No additional behavioral traits (rate limits, response structure) are disclosed beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: one sentence and a URL link. It is front-loaded with the core action. The link adds context but is not essential. No extraneous information, though the link could be integrated or omitted for brevity.
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 polling endpoint with one parameter and no output schema, the description covers the basic purpose. However, it lacks details about the response (e.g., status values, polling strategy) which would help an agent know when to stop polling. The external spec link partially compensates.
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 sole parameter exportId has no description in the schema or tool description. The description does not explain where to obtain the exportId (e.g., from a prior start call). Given 0% 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 'Poll status of an async license export job' with a specific verb ('poll') and resource ('async license export'). This distinguishes it from sibling tools like licenses_export_async_start (start) and licenses_export_async_download (download).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., sync export or status of other async jobs). The context implies it should be called after starting an export and before downloading, but this is not stated directly. There is no mention of polling intervals or completion conditions.
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 provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond stating the HTTP method (GET) and a spec link. It does not disclose auth requirements, error states, or response details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by a spec link. It is concise, front-loaded with the action and resource, and contains 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 absence of output schema and low schema coverage, the description is incomplete. It does not describe the return format, possible errors, or the relationship to other version-listing tools. However, the annotations cover safety aspects, and the spec link provides additional detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters appSoftwareId or buildNumber. It only mentions 'for a specific build number,' which partially clarifies buildNumber but leaves appSoftwareId undefined. The parameter names are somewhat self-explanatory, but no additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the resource 'version-listing for a specific build number.' It distinguishes from sibling tools like app_version_listing_create and app_version_listing_update by focusing on retrieval.
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 a specific build number but does not explicitly differentiate from related tools like app_version_listings_list_all or provide when-not-to-use guidance. Sibling tools exist for creation and updates, but no direct comparison.
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-readOnly behavior. Description adds 'partial update' but no further behavioral traits like auth needs or consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence and a link, front-loaded. Very concise, though could include more 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?
Given 2 params, annotations, and no output schema, the description is adequate but lacks details on response, prerequisites, or what fields can be patched.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 productId without description, body has a basic description. The text doesn't add meaning beyond 'partial update'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 patches cloud-migration compatibility info, with a spec link. It distinguishes from siblings like cloud_migration_compat_create and cloud_migration_compat_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives like create or get. The description only says 'partial update' 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?
Annotations already indicate mutation (readOnlyHint false) and potential destructiveness (destructiveHint true). The description adds 'single-use' but does not clarify the destructive aspect or other behavioral traits like idempotency or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with one sentence and a spec link. The link adds reference value but is not essential for an AI agent, slightly reducing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create tool with no output schema, the description should mention what the tool returns (e.g., the generated code or success status), which it does not. The spec link partially compensates but is not 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?
With schema description coverage at 0%, the description should compensate by explaining the parameter 'promotionId', but it does not. It only mentions 'for a promotion' without specifying how to identify it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action: generating a single-use code for a promotion, distinguishing it from sibling tools like promotions_code_delete, promotions_code_get, and promotions_codes_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (creating a code for an existing promotion) but provides no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true. Description adds context about 'PUBLIC IMPACT' and removing a publicly visible response, providing some additional insight beyond annotations. No mention of authorization or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: two sentences and a link, front-loaded with the action. No superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides a spec link and notes public impact, but lacks parameter explanations. For a simple delete tool, this is somewhat complete, but missing parameter docs leaves a 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 coverage is 0%, and the description does not explain the parameters (productId, reviewId) beyond showing them in the URL. It fails to add meaning to the parameter names and values, leaving the agent to infer 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 action 'Delete the vendor's response to a review' and specifies the resource. It distinguishes from siblings like review_response_put (create/update) and review_get (read) through the verb and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like review_response_put. The description mentions 'public impact' but does not provide when-not-to-use or compare with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. Description adds 'Get one version' which aligns but does not disclose additional behaviors like error handling or 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is one sentence plus a URL, concise and front-loaded. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with 2 required params and no output schema, description is adequate but lacks details about return format or error conditions. The URL to full spec compensates partially.
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 has 0% description coverage for parameters. Description mentions 'by build number' but does not explain appSoftwareId or the buildNumber type (string/number). Minimal added value over raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Get one version of an app-software by build number', specifying a specific verb and resource. It distinguishes from sibling tools like app_software_versions_list which lists all versions.
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-to-use or when-not-to-use guidance. The description provides a URL to the spec but does not compare with alternative tools like app_software_versions_list for listing all versions.
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 destructiveHint=true; description adds 'PUBLIC IMPACT (after approval)' context but does not elaborate on side effects or reversibility.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a link; very concise with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, body structure unexplained, no response info. The link to spec helps but description alone is incomplete for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only 33% schema coverage; body has vague description 'Version listing payload', and buildNumber/appSoftwareId have no description. The description text adds no 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 'Create a new version-listing for a specific build' with a specific verb and resource, and it distinguishes from sibling tools like get/update/list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creation, mentioning 'after approval', but lacks explicit alternatives or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. The description adds no behavioral details beyond a link to the API spec, which is supplementary but not essential for transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the essential action. The second sentence provides a reference link, which is optional but not distracting. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description is adequate but does not mention return values or error conditions, which would be helpful given the absence of 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?
Schema description coverage is 0%, so the description should compensate, but it only mentions 'by ID' without explaining what productId and reviewId represent. The agent may not know which ID is which.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get a single review by ID' with a specific verb and resource, distinguishing it from sibling tools like reviews_list and review_response_*.
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 purpose is clear but no explicit guidance on when to use this tool versus alternatives, such as when to use reviews_list instead. Only implied by the verb 'get' versus 'list'.
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?
Adds behavioral context beyond annotations by describing PUT semantics and that body is the full document. However, lacks details on error handling, prerequisites, or what happens on conflict. Annotations already flag destructive 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 plus a spec link, front-loaded with purpose. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description does not explain return value or success response. For a mutation tool creating a resource, this leaves the agent guessing about 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?
With 50% schema coverage, description clarifies that body is the 'full document' but does not explain productId or the structure of the body. Adds some meaning but insufficient to fully compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Create' and resource 'cloud-migration compatibility info for an app'. Distinguished from sibling tools 'get' and 'update' through naming and implicit contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage via tool name and PUT semantics, but does not explicitly state when to use this tool over siblings or provide exclusions. The spec link offers additional context but is not an inline guideline.
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, idempotentHint, and destructiveHint, ensuring the agent knows this is a safe read operation. The description adds minimal behavioral context beyond annotations, only noting it's a GET endpoint via the spec link.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a helpful spec link. No extraneous words, and the key information 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?
Given the simple single-parameter tool and rich annotations, the description is mostly adequate but omits mention of the return value (a developerId). Without an output schema, this would help contextual 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 description coverage is 0%, and the description provides minimal semantics for the vendorId parameter, only stating 'from a vendorId'. It lacks details on format, constraints, or examples, failing to compensate for the missing 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's purpose: 'Resolve a developerId from a vendorId (legacy mapping).' It uses specific verb-resource and distinguishes itself from sibling tools by calling out its legacy mapping nature.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'legacy mapping' but does not explicitly specify when to use this tool versus alternatives like developer_space_get or developer_space_listings. There is no mention of 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 value beyond annotations by stating the specific grant of console access ('AFFECTS OTHERS'). Annotations already indicate destructive=true, but description provides concrete impact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences plus a link, no wasted words. Front-loaded with key purpose and effect.
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 main effect and impact on others, but lacks details on return value, error conditions, or the default developerId. For a mutation tool with low param documentation, some gaps remain.
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 'body' described). Description does not clarify the 3 parameters (aaid, developerId, body) 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?
Clear verb 'Add' and resource 'user to developer space' with explicit effect 'grants console access'. Distinct from sibling member tools (get, remove, update, list).
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. The 'AFFECTS OTHERS' warning is generic, but no explicit when/not conditions or alternative tool mentions.
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 readOnly, idempotent, non-destructive. The description adds valuable behavioral context: it explains that certain parameters (productId, hosting, addon) are ignored, and describes the flat response structure without datasets or uniqueTotal. It also enumerates the series names for each metric value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a one-sentence summary, then details output structure, metric values, filter behavior, and a spec link. It is well-organized but slightly wordy; 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?
Given the absence of an output schema, the description covers the output format thoroughly, including series structure and addon arrays. It also notes ignored filters. However, it does not explicitly state that the data is scoped to the authenticated developer space or mention pagination limits.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the schema by explaining that only aggregation/startDate/endDate are used, and that metric values determine the series names (reasonKeys vs feedbackTypes). This helps the agent understand the impact of parameter choices.
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 feedback time-series grouped by a metric, with specific details on output structure and metric values. However, it does not explicitly differentiate from sibling tools like evaluations_by_metric or feedback_details, which handle similar data.
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 lacks guidance on when to use this tool versus alternatives. It mentions that only aggregation/startDate/endDate are effective filters, but does not explain when to choose this over other feedback or metrics 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 destructive and non-idempotent behavior. The description adds that it's a full replace (PUT) and that the information is not yet public, providing 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences plus a link and emoji. Information is front-loaded, with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks explanation of return values, side effects, or the relationship to published privacy-and-security information. Without an output schema, more detail is needed for 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?
The input schema has two parameters: body (with description 'Full privacy-and-security payload') and productId (no description). The description does not elaborate on parameter semantics or expected values, failing to compensate for the 50% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates or updates draft privacy-and-security information, specifies the HTTP method (PUT) and that it performs a full replace. It distinguishes itself from sibling tools like privacy_security_delete, privacy_security_get, and privacy_security_publish.
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 draft management (not yet public) and notes it's a full replace, but does not explicitly state when to use it versus reading (privacy_security_get) or publishing (privacy_security_publish). Guidance is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, openWorldHint=true. The description adds that it lists codes and includes a spec link, but does not elaborate on any behavioral traits beyond what annotations provide. No extra context on pagination, limits, or authorization is given.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core purpose. Every word is informative; no redundancy. The spec link is appended without cluttering the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple listing tool with one parameter and no output schema, the description is adequate but not comprehensive. It lacks details on response format, pagination, error handling, and prerequisites. Given the annotations cover safety, the description is minimally 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 0% (no description for promotionId in schema). The description hints that promotionId must be for a single-use promotion, but does not fully explain the parameter's format, constraints, or how to obtain it. The description only partially compensates for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists single-use codes for a SINGLE_USE_PROMOTION, using the verb 'list' and specifying the resource 'single-use codes'. It distinguishes from siblings like promotions_list (lists promotions) and promotions_codes_create (creates codes) by specific 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for single-use codes of a SINGLE_USE_PROMOTION, but does not explicitly state when to use it versus alternatives like promotions_list or promotions_code_get. No explicit when-not-to-use or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations: public impact of response. Also provides spec link. Annotations already indicate destructive write 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?
Two sentences plus a link, efficient. Front-loaded with action and impact.
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?
Sufficient for a simple 3-parameter tool. Covers action, public impact, and provides spec reference. No output schema 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?
Description does not explain parameter meanings. Only 33% schema coverage, and description adds no value for understanding parameters like productId or reviewId.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 action (post or update), resource (vendor response to a review), and important side effect (public visibility). Distinct from sibling tools like review_response_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. Does not mention alternatives 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?
Annotations already provide readOnlyHint, idempotentHint, etc. The description adds value by specifying that pagination and hosting filters are ignored, and by noting that productId is a path segment. This behavioral context goes beyond what annotations convey.
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, front-loading the purpose and return format. It includes a spec link for reference but avoids redundancy. Could be slightly more structured, but overall 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 no output schema, the description provides the return format. It covers the required parameter (productId) and filter parameters. With annotations providing safety profile, the description is fairly complete for a reporting query tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by listing the filters (aggregation/startDate/endDate) and noting that pagination/hosting are ignored. It also includes the return structure which implies parameter impact, exceeding the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Top search keywords for one app' and provides the return structure. It distinguishes the tool's scope (one app) but does not explicitly differentiate from sibling tools like search_keywords_by_app_export or search_keywords_by_source.
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. The description mentions filters but does not explain the use case or exclude other tools. For example, it does not mention that search_keywords_by_app_export is for exporting results or that other keyword tools focus on different sources.
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 discloses key behaviors: returns full JSON array directly (up to 500 rows), truncation on large responses, and that invalid accept format yields HTTP 400. Annotations already cover safety; description adds response format and 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 plus a spec link, no wasted words. Key information (export variant, direct JSON output) 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?
Provides output format, row limit, truncation behavior, and format options. Missing details on empty results and exact truncation mechanism, but adequate for an export 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?
Input schema already provides 100% coverage with descriptions for all 4 parameters. Description adds no new parameter semantics beyond the schema, meeting baseline for high 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?
Description clearly states it exports zero-result keywords as a JSON array. It distinguishes from HAL-download exports but does not explicitly differentiate from the base zero_search_results_keywords tool (non-export).
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 direct guidance on when to use this tool versus alternatives like zero_search_results_keywords or other export tools. The description implies it for full data vs. download links but lacks explicit selection criteria.
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, and idempotent behavior. The description adds the specific return fields and the HTTP 404 error for unknown builds, providing 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence for purpose, then a list of return fields, error note, and a spec link. While efficient, the return field list and link add some length without critical decision-making value for an agent.
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 lookup tool with no output schema, the description provides return fields and error behavior. However, the lack of parameter explanations makes it incomplete for agents that need to construct valid requests.
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 0%, so the description must explain parameters. It mentions 'buildNumber' in the path and the function, but does not describe what a build number represents or what 'parentSoftwareId' refers to. This is insufficient for an agent to select proper values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: 'Get a parent-software version by its build number'. It includes the specific API path, return fields, and distinguishes from the sibling 'parent_software_version_by_number' which uses a different lookup method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context through the path and error handling ('Unknown build → HTTP 404'), but it does not explicitly state when to use this tool versus alternatives, nor does it exclude any 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?
Annotations indicate destructiveHint: true, and the description reinforces this by stating 'promo code becomes redeemable by customers.' This adds context beyond annotations. However, it does not discuss idempotency or other behavioral traits explicitly, but annotations cover those.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences and a link. It front-loads the core action and required fields. Every word earns its place, with no fluff.
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 complex tool with 13 parameters and dependencies, the description is too brief. It lacks explanation of parameter relationships, output behavior, and edge cases. Although the schema and annotations provide some context, the description does not sufficiently compensate for the tool's complexity.
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 54%, yet the description only lists required fields without adding new meaning. It does not explain parameter interactions or provide context for undocumented parameters. The schema itself has descriptions for most parameters, so the description adds minimal 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?
Description clearly states 'Create a new promotion' with a specific verb and resource. The 'PUBLIC IMPACT' line adds clarity about the effect. It distinguishes from sibling tools like promotions_update and promotions_codes_create by focusing on creation.
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 lists required fields but offers no explicit guidance on when to use this tool versus alternatives like promotions_update or promotions_codes_create. It does not provide when-not or exclusion criteria, which would be helpful given the many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds critical 'GOTCHA: nonexistent/malformed promotionId returns HTTP 500 (not 404)' and return object size (~21 fields), going 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?
Three sentences: purpose, return details, GOTCHA. Front-loaded and efficient, no fluff. Could be slightly more concise but overall 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?
No output schema, but description compensates by listing key fields and providing a link to full spec. For a simple 1-param get tool, it provides sufficient context including error behavior and return 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 coverage is 100% with parameter description (UUID for Cloud, string for Server/DC). Description does not add additional parameter semantics beyond the schema, so baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Describes exactly what it does: get one promotion by ID. Distinguishes from siblings like promotions_list or promotions_create by specifying single resource retrieval.
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?
Only implies usage via 'Get one promotion by ID', but no explicit guidance on when to use this over alternatives (e.g., when you need a single promotion vs list, create, etc.). No when-not-to-use or alternative mentions.
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 safe read operations. The description adds important behavioral details: cursor-based pagination, default page size, error on invalid includePrivate, and dual output modes (summary vs raw). This 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?
The description is concise, packing essential information in a single paragraph. It could benefit from bullet points for readability, but it is front-loaded with the core purpose and well-organized.
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 an output schema, the description lists returned fields and explains pagination and output modes. It covers key aspects for a listing tool, though error handling beyond includePrivate is omitted.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all 4 parameters with descriptions. The description reinforces key semantics: cursor usage, default limit of 10, effect of includeFullPayload, and error on invalid includePrivate. It adds practical context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists apps in a developer space, mentioning the fields returned and that it's a live API call. It doesn't explicitly distinguish from siblings like developer_space_listings or apps_known, but the name and context make its purpose clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains pagination, parameters like includePrivate and includeFullPayload, and defaults. However, it lacks guidance on when to use this tool versus alternative listing tools, nor does it specify prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate mutability (readOnlyHint=false, destructiveHint=true). The description adds the critical behavioral detail that the returned token is shown only once and must be stored securely, which exceeds 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?
The description is brief (two sentences and a link), front-loaded with the action, and every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description includes a security warning and spec link but omits what the tool returns (the token itself). With no output schema, the agent lacks complete context for handling the response.
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 `body` has a description). The tool description does not elaborate on parameters or their semantics, so meaning beyond the schema is absent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Create' and the resource 'access token for this app-software', distinguishing it from sibling tools like `app_software_tokens_list` which lists tokens.
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 security warning and a spec link but lacks explicit guidance on when to use this tool over alternatives (e.g., when to create vs. list tokens). Usage is implied but not clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds value by mentioning downstream service usage and providing a spec link, 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?
Extremely concise: one sentence plus a spec link, front-loaded with the core action. 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?
For a simple getter with one optional parameter and no output schema, the description is adequate but lacks explanation of the return value structure or format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description does not explain the developerId parameter's purpose or format, relying on the parameter name alone which is insufficient for optimal selection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Get) and resource (catalog-account ID for a developer space), and distinguishes from siblings like developer_space_get by specifying the exact ID returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when needing the catalog-account ID, but provides no explicit guidance on when to use this tool vs alternatives or any exclusion criteria.
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, idempotent, and non-destructive. The description adds behavioral detail about the return format (bare array not envelope) and provides a spec link. 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?
Concise two sentences plus a hyperlink. Front-loaded with the action and resource. No unnecessary 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?
Despite simplicity, the description lacks documentation for the single parameter and does not describe the output beyond 'bare array'. A brief mention of what 'developerId' represents would improve completeness.
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?
Input schema has one parameter with 0% description coverage. The description does not explain the 'developerId' parameter, its purpose, or format, failing to compensate for the missing 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?
Clearly states it gets developer-profile listing documents and specifies the return format as a bare array. Distinguishes from sibling 'apps_list' by explicitly saying it is NOT for product apps.
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 guidance on what the tool retrieves and explicitly directs users to a sibling tool ('apps_list') for a different use case. However, it does not address when to use this tool over other listing-related siblings like 'app_listing_get'.
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 (readOnlyHint, etc.), the description adds critical context about non-standard cursor pagination shape, page size limits, and links to API spec, clarifying behavioral nuances.
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: purpose first, then return shape, pagination specifics, and spec link. Information-dense without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with no output schema, the description adequately documents return shape, pagination mechanism, and parameter behavior. The spec link provides further reference.
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 67% schema coverage, the description adds practical usage details for limit and cursor (e.g., 'pass its value straight back') beyond schema descriptions, though developerId remains minimally explained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists team members in the developer space and specifies the return shape and pagination, but does not explicitly differentiate from sibling list tools like developer_space_listings.
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?
Provides detailed pagination usage instructions but no explicit guidance on when to use this tool versus alternatives (e.g., developer_space_member_get for single member).
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 (readOnly, idempotent, non-destructive), description adds value: notes PII sensitivity, pagination via _links.next, and references the spec URL. Provides behavioral context not captured by annotations alone.
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?
Description is front-loaded with purpose but includes inline return format (could be output schema). Some redundancy with schema descriptions. Could be more concise, e.g., by moving long return field list to output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description adequately covers return fields, pagination, and PII warning. Includes spec URL for details. However, I deduct for not clarifying differentiation from sibling feedback 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?
Schema coverage is high (92%), so the schema already documents parameters well. The description mentions filterable fields collectively but adds little semantic value beyond the schema. Appropriate baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states it returns raw customer feedback entries (uninstall/disable/unsubscribe) with reasons and free-text messages. Specifies return format fields and pagination. Clearly identifies its resource and scope, distinguishing it from aggregated feedback tools like feedback_metrics_by_metric.
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 detailed raw feedback data by listing filters, but no explicit when to use vs. alternatives or when not to use. The sibling list includes feedback_metrics_by_metric, but the description does not clarify the distinction.
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, idempotent, non-destructive. The description adds a noteworthy behavioral detail about the shared path and provides a direct spec link, 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?
Two concise sentences with a useful link. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides purpose, behavioral nuance, and a reference, but does not describe the return value or indicate what the status response looks like. Since there is no output schema, the agent lacks this information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one required parameter ('exportId') with 0% schema description coverage. The description does not explain this parameter's meaning or format; it relies on the parameter name. Some additional context would be helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Poll status of an async marketing-attribution export job,' specifying the verb 'poll' and the resource 'status.' This distinguishes it from related tools like 'start' and 'download' for the same export type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use after starting an export by saying 'poll status,' but does not explicitly state when to use this tool versus other async status tools (e.g., for licenses or transactions). No exclusion criteria or alternatives given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds value by specifying the exact status values returned (ACTIVE, ENDED_EARLY, EXPIRED). 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 extremely concise: one sentence plus a link to the API specification. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple (one parameter, returns status string), the description omits mention of the partnerId (implied in URL but not in input schema) and does not cover error cases or the response structure beyond status values. With no output schema, some additional context 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 0% and the description does not describe the promotionId parameter. Although the parameter name is self-explanatory, the description should at least mention it or explain its format, given the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves the status of a promotion, listing the possible values (ACTIVE, ENDED_EARLY, EXPIRED). This specific verb+resource combination distinguishes it from sibling tools like promotions_get or promotions_list.
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 obtaining status only, but does not explicitly differentiate when to use this tool versus alternatives like promotions_get for full details. No guidance on when not to use it is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral detail about the response structure, region values, and that usersPercent sums to ~100. It also notes that productId/hosting are ignored, which is 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 concise and front-loaded with the main purpose. Each sentence adds value (response shape, region list, filtering note, spec link). The link to external spec is slightly extraneous but does not detract significantly.
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 no output schema, the description adequately explains the return structure, filtering, and region values. It covers key aspects like usersPercent summing to ~100 and the benchmark. Minor gaps remain, such as not clarifying the optionality of the benchmark.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds context about filtering behavior and response structure, but does not significantly go beyond the schema's parameter descriptions. 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: 'Geographic-region distribution of your customers' users, per month.' It specifies the verb (returns distributions) and the resource (customer users' geographic regions). It distinguishes from sibling tools like customer_insights_active_users by focusing on regions.
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 usage context by stating that only startDate/endDate filters work and that productId/hosting are ignored. However, it does not explicitly tell when to use this tool versus alternatives 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds behavioral context beyond annotations: it reveals that the return contains PII (email, userName), and that an unknown aaid results in HTTP 400. This is valuable transparency not covered by annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences followed by a spec link. It is efficiently front-loaded: the first sentence states the core purpose, and the second adds return format and an error condition. 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 get tool with no output schema, the description adequately covers the return fields (including PII) and an error case. It provides a link to the full spec. It could be improved by noting the default developerId behavior, but overall it is complete enough for 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 50% (only aaid has a description). The description does not add any parameter details beyond what the schema provides. It merely mentions aaid without elaborating on format or usage. The developerId parameter is not explained anywhere, and 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get one developer-space team member by Atlassian account id (aaid).' It specifies the verb (get), resource (developer-space team member), and identifier (aaid). Among siblings, there are distinct tools for adding, removing, listing, and updating members, making this tool easily distinguishable.
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 implicitly suggests use when you have a specific aaid but provides no explicit guidance on when to use this tool versus alternatives like developer_space_members_list. The only usage hint is the error condition for unknown aaid. No when-not-to-use or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds useful context about including usage info if redeemed, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is short and front-loaded with key action. The link to spec is optional but not wasteful. Could be slightly more compact but overall 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?
Description covers the main purpose and includes a spec link for details. Given simple read operation and good annotations, it is fairly complete. Could mention required parameters or response shape briefly.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% with only promotionCode having a description. Description doesn't elaborate on parameters beyond implying the code identity. Provides minimal additional meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get one single-use code (including usage info if redeemed)', specifying the verb and resource, and distinguishes from sibling tools like promotions_codes_list and promotions_code_delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description implies use for retrieving a single code with usage info, but provides no explicit guidance on when to use vs alternatives like promotions_codes_list. Lacks when-not or alternative suggestions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description accurately notes the async nature and the response format, which goes beyond annotations. Annotations indicate it's a non-read-only, non-idempotent, non-destructive operation, and the description does not contradict this. It could improve by detailing that the job runs asynchronously and requires polling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a link. It front-loads the core purpose and return value, contains no filler, and every sentence adds value. The link to full documentation is appropriate.
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 20 parameters and no output schema, the description should cover the async workflow. It mentions returning an ID for polling but does not explain the subsequent steps (status check via transactions_export_async_status, download via transactions_export_async_download). This omission leaves the agent without a complete understanding of the process.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 tool description does not add new parameter-level meaning beyond what is already provided in the input schema. The schema itself has 60% description coverage with descriptions for many parameters (e.g., text, accept, startDate). The description only mentions 'accept' in passing, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Start an async transactions export job' and specifies the return value as '{export:{id}}' for polling. It distinguishes itself by mentioning the asynchronous nature and the accept parameter for format selection, leaving no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells you to use it to start an async export and poll the returned ID, but it does not compare with siblings like transactions_export_sync or transactions_list. There is no explicit guidance on when to choose this tool over alternatives, which is needed given the large sibling list.
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 cover readOnly and idempotent hints. Description adds context of polling async job, consistent with 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?
Very concise single sentence with optional link. No wasted words, front-loaded 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?
Adequate for a simple polling tool with one parameter and no output schema. Could mention workflow context, but annotations fill gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and description does not explain exportId parameter (e.g., how to obtain it, format). Minimal added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'poll' and resource 'status of async transactions export job', distinguishing from siblings like start and download.
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-to-use or alternatives, but tool name implies usage after starting an export. Lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark destructiveHint=true, so no duplication. The description adds valuable context: 'PUBLIC IMPACT: changes appear on the app's marketplace page after approval,' which discloses the approval delay and visibility impact. 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 plus a link, front-loaded with the core purpose. Every sentence adds value: purpose, public impact, PUT semantics, and a spec reference. 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 core behavior (update, PUT, full object), public impact, and spec link for details. Lacks explicit error handling or auth notes, but openWorldHint suggests these are handled elsewhere. Sufficient for an update tool with a spec reference.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% (only body has a description). The description reinforces that body must be a 'full listing object,' but productId remains undocumented. This partial compensation keeps the score 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 clearly states 'Update Marketplace product listing metadata' with specific verb and resource. It distinguishes itself from siblings like app_listing_get and app_version_listing_update by mentioning PUT semantics and full listing object replacement.
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?
Guidance is partially provided: it notes that the body should be a full listing object (PUT semantics), but it does not explicitly contrast with alternative tools (e.g., when to use app_version_listing_update instead) or specify prerequisites like required permissions.
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 safety (read-only, idempotent). Description adds return format and error handling specifics, enhancing behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with a link. Front-loaded essential information, 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?
Sufficient for a simple read tool: specifies return fields, error condition, and default parameter. Link provides additional reference. No output schema so describing return shape is good.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 description. Description merely restates default. No added 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 'Get developer space profile by developerId', lists return fields, and distinguishes from sibling tools like developer_space_by_vendor.
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?
Provides default behavior and error handling, but no explicit guidance on when to use this tool over alternatives. Adequate but lacks selection advice.
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 it's not read-only or destructive, and the description adds the async pattern and return envelope. It could mention resource usage or job limits, but overall it's 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 concise sentences plus a spec link. No wasted words, front-loaded purpose, and clear formatting.
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 complex 24-parameter async tool with no output schema, the description covers the async flow and accept format but omits any detail about the filter parameters that define the export content. Partially 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?
With 58% schema coverage and no description of the 24 parameters beyond `accept`, the description fails to compensate. Most parameters are crucial for filtering the export and are left to the schema, which has gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool starts an async license export job, returns an ID to poll, and distinguishes it from siblings like licenses_export_async_status (poll) and licenses_export_async_download (download). It also provides a spec link.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool (to start an async export) and the subsequent polling/download steps. It implies the sync alternative exists but does not explicitly state when not to use it. The spec link adds 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 already mark destructiveHint=true and readOnlyHint=false, so the description adds value by clarifying that only the draft is deleted and the published version is unaffected. This context goes beyond what annotations provide, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that clearly states the action and impact, followed by a link to the spec. It is front-loaded and contains 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?
The tool is simple with one parameter, and annotations cover destructiveness. However, the description lacks any explanation of the productId parameter, which is critical for correct invocation. No output schema exists, but the description could mention expected return behavior. Overall, adequate but not fully complete.
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?
With 0% schema description coverage for the only parameter (productId), the description must explain its meaning and usage. It does not mention productId at all, leaving the agent without guidance on what value to provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 the draft privacy-and-security info, distinguishing it from the published version. The verb 'delete' and resource 'draft privacy-and-security info' are specific, and it differentiates from siblings like privacy_security_get and privacy_security_draft_put.
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 (to delete a draft) and contrasts with the published version, but does not explicitly provide when-not-to-use or alternatives. The link to the spec may offer more, but in the description itself guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds PATCH semantics and partial update behavior beyond annotations (destructiveHint=true). With annotations present, this is 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?
Description is one succinct sentence with a link, front-loading the key behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema is provided, and the description does not mention return values or success criteria. The external link helps but does not fully compensate for the missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description adds no parameter-level details. Parameter names are somewhat self-explanatory, but the description should compensate for the missing 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 updates a promotion using PATCH, specifying that only supplied fields change. This distinguishes it from sibling tools like promotions_create and promotions_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via 'PATCH — only supplied fields change' and siblings provide alternatives, but it lacks explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds behavioral details: no aggregation, pagination ignored, and raw data returned. This goes beyond the annotations by clarifying how the tool operates on the data, though it does not cover rate limits or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with purpose and output format, and includes only essential details. The URL to the full spec is efficient and avoids redundancy. 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 params, read-only, no output schema), the description covers purpose, output, filters, and behavior (no aggregation, pagination ignored). It provides a link to the full spec for completeness. Could mention typical use cases or limitations, but is adequate for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions startDate/endDate as filters and notes that pagination is ignored, but does not add new semantic meaning beyond what the schema already provides. The schema already describes the sourceKey restriction clearly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns keywords with zero search results for a single source, explicitly for SEO gap analysis, and specifies the output format as `{details:[{searchKeyword, count}]}` with count indicating frequency. This distinguishes it from other keyword tools like search_keywords_by_source, which return all keywords, and from the export sibling.
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 identifying missing keywords, but does not explicitly state when to use this tool vs alternatives like search_keywords_by_source or the export variant. It does provide useful guidance that only `marketplace` is supported and that `embedded-marketplace` will be rejected, but lacks general usage 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?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the error case for unknown productId and lists return fields, providing some extra context but not extensive behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus a link. Front-loaded with purpose and return fields, no unnecessary words. 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?
For a simple read-only get tool with one parameter and no output schema, the description explains the return format (list of fields) and error behavior. It is complete given the tool's complexity and the annotations 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 coverage is 100% for the single parameter 'productId'. The description adds value by stating that unknown productId returns HTTP 404, beyond the schema's 'Product UUID' 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 'Get Marketplace product listing metadata for one app' with specific verb and resource, and lists return fields. It distinguishes from sibling tools by specifying 'Marketplace product listing'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives. The description implies usage for fetching one app's listing by ID, but lacks comparison to sibling tools like app_software_get_by_appkey or app_version_listing_get.
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, idempotent, non-destructive. Description adds timeout behavior (10 min, overridable via env var) and that it returns JSON array. 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 plus a URL, no wasted words. Front-loaded with purpose, then key behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return value, prerequisite, timeout, and spec link. Lacks output structure details, but tool is simple and output is a 'JSON array of license records'.
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?
Only one parameter (exportId) with 0% schema coverage. Description does not explain exportId beyond implying it is the export identifier from the status endpoint. Lacks explicit semantic guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool downloads a completed async license export and returns a JSON array of license records. It distinguishes itself from sibling tools like licenses_export_async_start and licenses_export_async_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to call only after the *_status endpoint reports DONE, otherwise a 404 is returned. Also mentions timeout override. Does not explicitly compare with alternatives like licenses_export_sync, but guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral context about pagination, offset/limit, and searching by SEN, which is useful beyond annotations. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a link, with front-loaded purpose and key usage. Every sentence adds value, and the link provides additional detail. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal for a 23-parameter tool with no output schema. It provides enough to get started (pagination, search), but many filtering options are not addressed. The link to the spec helps, but the description alone lacks completeness for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 57%, so moderate. The description adds meaning for pagination (offset/limit) and the 'text' parameter (find by SEN), but does not explain most other parameters. It partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 licenses for the developer space, is paginated with offset/limit, and highlights a specific use case (using 'text' to find by SEN). This verb+resource combination is distinct from sibling tools like licenses_export_sync or licenses_export_async_start.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to list licenses, paginated) and hints at a specific use (find by SEN). However, it does not explicitly exclude alternatives or provide guidance on when to use sibling tools like exports. The context is clear but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds value by disclosing that a wrong body shape results in an HTTP 400 with a JSON-parse error, which goes 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 well-structured: it starts with a clear purpose, then details the body shape, highlights important notes, mentions error behavior, and describes pagination. While slightly long, every sentence adds value and the critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the body shape, error handling, and pagination, but does not describe the return value format. Since there is no output schema, the agent may lack understanding of what the response contains. The inclusion of a spec link partially compensates but does not fully address the gap.
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 provides extensive detail on the body parameter's shape, including nested objects, required fields, and specific constraints (e.g., 'metrics is an OBJECT, not an array'). This goes well beyond the schema's minimal description, especially since the body schema only has a generic reference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'Fetch partner-metric time series', specifying a concrete verb ('Fetch') and resource ('partner-metric time series'). This clearly distinguishes it from sibling tools like metrics_churn or metrics_conversion, which focus on specific metric categories.
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 how to use the tool (e.g., body shape, pagination) but does not provide guidance on when to choose this tool over alternatives. No explicit when-not-to-use or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds that the version becomes visible to all visitors and reviewers, extending 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 that are front-loaded with purpose and impact, plus a reference link. 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 simple one-parameter tool with annotations declaring destructiveness, the description covers purpose and outcome well. However, it could mention prerequisites (e.g., draft must exist) or post-publish state.
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 single required parameter productId has no description in the schema or the tool description. With 0% schema coverage, the description should compensate but does not explain what productId refers to or how to get it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Publish the current draft privacy-and-security info') and its public impact, distinguishing it from sibling tools like privacy_security_draft_put or privacy_security_get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context by noting the public impact and visibility, implying when to use. However, it does not explicitly mention when not to use or compare to alternative tools, though 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 readOnly and non-destructive hints. The description adds valuable behavioral context: cursor-based pagination, the exact return structure, and a warning about PII in reviews. These details go beyond the annotations, justifying a 4.
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 fairly concise with front-loaded purpose. It includes pagination, return format, and PII warning in a structured way. The spec link adds length but is an optional extra. Could be slightly tighter, but overall effective.
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 5 parameters and no output schema, the description is complete. It explains pagination, return fields, and a PII note, covering the essential aspects. The spec link provides additional details if needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions (e.g., sort enum with invalid value warning, cursor explanation). The description adds a PII note but no additional parameter-level detail. Since the schema does the heavy lifting, a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List customer reviews for an app', specifying the verb (list) and resource (customer reviews). It also distinguishes itself by noting cursor-based pagination, setting it apart from any offset-based list tools among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about the tool's function and pagination behavior, but it does not explicitly state when to use this tool versus alternatives like review_get or other list tools. The purpose is clear enough that an agent can infer usage, but explicit guidance is missing.
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 safe read-only and idempotent behavior. The description adds value by disclosing the return format (JSON array of {searchKeyword, percentage} rows, up to 500) and the truncation behavior for large responses. It also notes that invalid inputs cause HTTP 400 errors, 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with two informative sentences plus a spec link. Every sentence serves a purpose: identifying the tool, contrasting with siblings, and specifying return behavior. The link to the API spec is additional but not essential. Overall, it is well-structured and 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 absence of an output schema, the description adequately explains the return format (JSON array of rows, up to 500, truncation for large responses). It covers the key behavioral aspects but does not elaborate on error handling beyond invalid parameter HTTP 400 or the exact CSV format. For a read-only export tool, this provides sufficient context for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 repeats the meaning of the `accept` parameter (json default, csv returns CSV string) and sourceKey enum values, but does not add substantial new information beyond what the schema provides. Therefore, it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as an export variant of source-filtered search keywords, specifying the resource ('search keywords filtered by source') and the verb ('export'). It explicitly contrasts with sibling tools (search_keywords_by_app_export, search_keywords_partner_export), stating that this tool returns the FULL DATA directly as a JSON array rather than HAL download links, which differentiates it from similar exports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('UNLIKE the partner/by_app exports, this returns the FULL DATA directly') and mentions expected behavior (up to 500 rows, truncation for large responses). It does not explicitly list when not to use it or a direct alternative, but the contrast with other export tools implies the use case.
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, idempotent, non-destructive. The description adds behavioral context: synchronous nature, output format behavior (CSV string vs JSON array), and timeout details. This goes 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 plus a link are highly concise. The purpose and key format guidance are front-loaded. Every sentence adds value—no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 20 parameters and no output schema, the description omits details like default sorting, pagination behavior, and full field list in output. The spec link partially compensates, but the description alone is not fully self-contained for an agent to understand all important 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?
With 60% schema description coverage, many parameters already have descriptions in the schema. The description only adds context for the 'accept' parameter (default CSV) and the timeout env variable. It does not significantly enhance parameter understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Synchronous export of transactions' and specifies the output formats (CSV default, JSON). It explicitly contrasts with async variants by recommending async for large ranges, effectively distinguishing this tool from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description provides explicit guidance to prefer async for large ranges and mentions the 10-minute timeout (overridable). While it doesn't list all alternatives among the many sibling tools, the key usage advice is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, etc. The description adds that it's an aggregate (not a list) and that hosting/pagination parameters have no effect, which provides 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is informative but contains a long JSON snippet and spec link, making it a bit verbose. It could be more concise while retaining key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but the description provides the full output format (JSON structure) and a spec link. It covers filtering and ignored parameters but does not explain each output field's meaning.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and schema descriptions are adequate. The description adds value by clarifying that addon and productId are alternative filters and that hosting/pagination are ignored, which provides meaning beyond schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's for Marketplace 'request app' / 'approve app' activity per month, benchmark-style aggregate, and explicitly says it's NOT a paginated list. This distinguishes it from sibling tools like licenses_list or transactions_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises filtering by addon or productId and notes that hosting/pagination are silently ignored. This gives clear context on how to use the tool, but lacks explicit when-not-to-use or alternative tool comparisons.
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 readOnly, idempotent, non-destructive. The description adds behavioral detail beyond annotations by explicitly noting the response structure's wrapper key ('totals' plural) and differing per-month keys between total and addon levels. This is valuable context for correct parsing and aligns 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 detailed but front-loaded with purpose and return structure. It includes a spec link and important structural notes. While not overly verbose, it could be slightly more concise without losing key information. Still efficient for the 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?
For a tool with 4 optional params, no output schema, and reporting complexity, the description fully details the return structure with field names and nesting. It also links to the full API spec. No critical gaps identified, making it 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% with good descriptions for all 4 parameters. The description adds marginal value by noting that productId works despite not being in the HAL template, and that hosting/aggregation is ignored. This extra nuance justifies a score above 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 clearly states the tool provides 'Evaluations benchmark vs. ecosystem, per month.' This is a specific verb and resource, and the detailed return structure adds clarity. It distinguishes itself from siblings like 'benchmark_sales' and 'evaluations_by_metric' by focusing on benchmark evaluations.
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 filtering by addon/productId and that hosting/aggregation is ignored, but does not explicitly state when to use this tool versus alternatives. There is no guidance on exclusions or when-not-to-use. Usage is implied through context but not articulated.
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, idempotentHint, destructiveHint false. Description adds behavioral detail such as ignoring hosting/aggregation and explains the meaning of *Percentile and *BenchmarkAllPartners fields, enhancing transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Starts with a summary, then output structure, then filtering notes, then spec link. Some redundancy in output example, but overall 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?
Despite no output schema, the description exhaustively documents the return shape and key metrics. Includes filtering behavior and a link to the full API spec, making it self-contained for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a description. Description adds that addon and productId are alternatives but does not provide additional semantic value beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it returns 'Sales benchmark vs. ecosystem, per month' and details the output structure with fields like salesPercentile and salesMoMGrowth. Distinguishes from siblings like benchmark_evaluations by specifying sales focus.
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?
Specifies filtering by addon or productId and notes that hosting/aggregation are ignored. Provides a spec link for full context but lacks explicit guidance on when to use this vs other benchmark tools like metrics_churn_benchmark.
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, idempotentHint, destructiveHint. Description adds behavioral traits: silent ignoring of certain filters, time-series structure, and breakdown details. 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?
Front-loaded with key information and includes a spec URL. A bit verbose but earns its length with useful details. No redundant sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (time-series, multiple series, per-app breakdown, filter constraints) and absence of output schema, the description fully explains what is returned, how to compute rate, and which parameters work. Agent has enough 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% with clear descriptions for all 3 parameters. Description adds value by explaining that only these 3 filters are effective and others are ignored, enhancing the parameter 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?
Clearly states 'Cloud churn TIME-SERIES (not a single rate)' and specifics what it returns: total.datasets split by billing period with two series per period, plus per-app breakdown. Distinguishes from a simple rate computation.
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 that only 3 filters work (aggregation/startDate/endDate) and others are silently ignored, and that caller must compute rate. However, does not compare to sibling tool metrics_churn_benchmark or provide when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making safety clear. The description adds value by specifying the 404 error on unknown versions and describing the return shape. This is useful behavioral context beyond the 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?
The description is concise (three sentences) and front-loaded with the core action. The spec link provides additional detail without bloating the main text. 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?
Despite no output schema, the description defines the return shape by referencing `version_by_build` and listing fields. Error behavior (404) is covered. The spec link fills any remaining gaps. It is fairly complete for a simple lookup tool, though it could mention rate limits or auth requirements more explicitly.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 two parameters (versionNumber, parentSoftwareId) with 0% schema description coverage. The description partially compensates by explaining that versionNumber is a human-readable version number and the endpoint path shows both parameters' roles. However, it does not explicitly describe each parameter or what parentSoftwareId represents, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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: 'Get a parent-software version by its human-readable version number'. It includes the specific endpoint path and an example ('11.3.8'). It distinguishes itself from the sibling tool `version_by_build` by noting the same record shape but a different lookup method.
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 usage context by indicating the lookup by version number and the HTTP 404 behavior for unknown versions. It implies an alternative (version_by_build) but does not explicitly state when to use this tool versus others. The context is clear but lacks explicit when-not 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?
Annotations already indicate read-only, idempotent, non-destructive. The description adds value by detailing the return array structure, explaining complianceBoundaries scope, and noting error behavior for invalid hosting.
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, front-loads the purpose, and includes a helpful spec link. While not overly verbose, it packs useful information into a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes the return format and key constraints. It covers hosting, complianceBoundaries, and error cases. Could mention that results are typically one per hosting platform, but overall 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 descriptions cover 100% of parameters. The description adds extra context: example for appKey, explanation that invalid hosting causes 400, and complianceBoundaries as Cloud-only. This adds 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 looks up app-software by appKey and specifies the return structure (ARRAY of fields). It distinguishes the tool as focusing on the technical artifact behind a product listing, which sets it apart 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides guidance on using hosting to narrow results and warns that invalid hosting returns HTTP 400. Mentioning complianceBoundaries as Cloud-only adds context. However, it does not explicitly state when not to use this tool or compare to 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?
Description adds value beyond annotations by explaining async workflow and that identical params yield the same exportId. Annotations provide basic hints (readOnly, destructive), but description discloses behavior not captured there. 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 plus a spec link, all front-loaded with essential information. No extraneous text. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and presence of annotations, the description covers async flow, filters, dedup, and response format adequately. No gaps identified for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 6 parameters. Description merely lists the filters without adding new semantics beyond what schema provides. Baseline 3 is appropriate as description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (start), resource (async export of marketing-attribution data), and distinguishes from sibling async exports (licenses, transactions) by resource name. Mentions response format and filters, providing specific purpose.
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 describes the async flow: start returns id, then use status and download tools. Mentions parameter deduplication. Does not explicitly state when not to use or compare with siblings (e.g., sync export), but the context is clear enough for agent inference.
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, idempotentHint=true, etc. The description adds pagination details and API link, but does not provide extensive behavioral context beyond what annotations 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?
Two sentences plus a link, front-loaded with purpose, no wasted words. Efficient and informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with cursor pagination, the description covers purpose, pagination mechanics, default behavior, and provides a link to the API spec. No gaps identified.
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 explaining how limit and cursor work together for pagination, going beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists parent software (Atlassian products) and distinguishes it from siblings like parent_software_get by noting it returns all ~23 products.
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 pagination with limit and cursor, but does not explicitly say when not to use this tool or mention alternatives. However, the context is clear enough for most uses.
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, idempotentHint, destructiveHint. The description adds specific pagination behavior (cursor-based) and references the REST endpoint, which goes beyond the annotations and provides 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 concise (two sentences plus a link), front-loaded with purpose, and every sentence adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (list endpoint, no output schema), the description adequately explains pagination and provides a link to the full API spec. It is complete enough for an AI 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?
The input schema has 67% description coverage, with limit and cursor well-described. The description reinforces cursor pagination but does not add new parameter semantics beyond what the schema provides. A score of 3 is appropriate as the description adds minimal extra value for 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 'List known versions of a parent software' with a concrete example (Jira versions). It distinguishes this listing tool from sibling tools that fetch specific versions (parent_software_version_by_build, parent_software_version_by_number).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions pagination and provides a spec link, offering clear context. However, it does not explicitly state when to use this tool versus alternatives (e.g., when to use parent_software_versions_list vs app_software_versions_list), though the naming implies the scope.
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 return object structure, state parameter effects (default, 404, 400), and a link to external spec. Annotations already indicate read-only, idempotent, non-destructive; description provides complementary detail 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two paragraphs: first states purpose, second details return and state. Efficient, no wasted words. Link to spec is helpful but could be integrated.
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 2 params, no output schema, and annotations present, description provides return structure, state details, and external link. 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.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (productId lacks description). Description compensates by fully explaining state behavior (valid values, default, error responses). Does not elaborate on productId, but parameter name and type are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get privacy & security information for an app', specifies audience (enterprise procurement reviewers), and distinguishes from sibling tools like privacy_security_draft_delete and privacy_security_publish which are write 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?
Mentions intended audience and state parameter behavior (live default, draft 404). Implicitly separates from write operations, but lacks explicit 'when not to use' or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and destructiveHint=false, but the description adds that the response is a HAL response, which is a useful behavioral detail beyond what annotations provide. The spec link offers additional reference.
Agents need to know what a tool does to the world before 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, efficient sentence plus a spec link. No wasted words, and the key information (purpose, resource, response format) is front-loaded.
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 sufficiently explains that the tool returns a HAL response with reporting links. The spec link provides completeness. Annotations cover safety. 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?
With zero parameters and 100% schema coverage, the description correctly adds no parameter details. The high baseline (4) applies because the schema already fully documents parameters (none exist).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the reporting root with a HAL response listing all available reporting links. The verb 'Get' and resource 'reporting root' are specific, and it distinguishes from sibling tools like metrics_churn or benchmark_evaluations by indicating this is a discovery endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. While it's straightforward, the description could mention that this tool should be used first to discover available reporting endpoints, then other tools (e.g., metrics_churn) for specific data. The context is implied but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the silently ignored productId behavior, provides HAL template and spec link. Annotations already indicate safe read-only operation; description adds valuable context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise with front-loaded purpose. Includes spec link and note, but no wasted words. Slightly dense but acceptable.
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, but description explains alias nature and behavior. Lacks any hint about return format. Adequate but not 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 coverage is only 33% (only aggregation described). The description does not elaborate on startDate/endDate parameters. Limited added value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it's a friendly alias for transactions_aggregate_by_metric with metric='hosting'. Distinguishes from sibling by noting the productId behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use the sibling instead (when productId scoping is needed) and documents that productId is silently ignored here.
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, destructiveHint=false, openWorldHint=true, idempotentHint=true. The description adds behavioral context not in annotations: that specific filters are ignored, and it outlines the response structure (usersDistribution fields). No contradictions detected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences plus a spec link. The first sentence states the purpose, the second clarifies filters and response structure. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the response structure (usersDistribution fields). Parameters are fully described. For a simple read-only tool with two optional parameters, this is complete enough. Could mention potential empty results, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters have clear schema descriptions (ISO date format). The description adds meaning by explaining that they filter 'monthly distribution buckets' and that other filters are ignored, which goes beyond the schema alone. Schema coverage is 100%, so this is strong.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 retrieves 'paid-vs-non-paid active-user distribution across the customer base, per month,' specifying the group key and bucket values. It distinguishes from sibling tools by noting that productId/hosting/product filters are ignored, making the purpose and 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states that only startDate/endDate filters apply and that other common filters (productId/hosting/product) are ignored, providing clear guidance on valid usage. It could be improved by explicitly referencing sibling tools for alternative breakdowns, but the current guidance is 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?
While annotations already provide readOnlyHint, idempotentHint, etc., the description adds valuable behavioral context: potential 5xx errors on large ranges, specific timeout behavior, and format handling (accept parameter). 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?
Description is concise and well-structured: opens with purpose, then key caveats, then spec link. Every sentence adds necessary information without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (24 parameters, no output schema), the description covers critical behavioral aspects (sync vs async, timeout, error cases, format). Could mention exact return type (CSV string vs JSON array) but the 'accept' description helps. Spec link provides fallback.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 58%, and the description does not significantly enrich parameter understanding beyond the schema. It mentions the 'accept' parameter's effect but doesn't elaborate on other parameters. 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 function: synchronous export of licenses. It specifies output formats (CSV/JSON) and distinguishes from sibling async variants, 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?
Explicit guidance: 'May 5xx on large ranges — prefer the async variant' provides clear when-to-use and when-not-to-use criteria. Also mentions configurable timeout, aiding correct 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 indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context: request timeout (10 min, overridable) and error scenario (404 if not done). This enriches 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 plus a spec link. No wasted words; critical info (purpose, precondition, timeout, error) is front-loaded. The link provides optional 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 single parameter and no output schema, the description covers essential behavior: what it does, when to use it, timeout, and error handling. It is nearly complete for a download tool, though output format details are minimal.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only one parameter (exportId) with 0% schema description coverage. The description implies it's the ID of the completed export but does not explicitly define the parameter format or source. Slightly below baseline due to coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Download a completed async marketing-attribution export' with a specific verb and resource, distinguishing it from related start and status tools. The return type 'JSON records' is also specified.
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 to only call after the *_status endpoint reports DONE, otherwise a 404 error occurs. This provides clear when-to-use guidance and preconditions.
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 provide readOnlyHint and idempotentHint. The description goes well beyond by detailing the exact output shape (flat series, two series names, no uniqueTotal, addons structure), the ignored filters, and empty responses for invalid ranges. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with key distinguishing shape information and provides efficient, detailed explanations of output structure, parameter behavior, and edge cases. The URL adds minor redundancy but overall 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 no output schema, the description thoroughly explains the response structure, series names, calculation requirement, and parameter constraints. It covers all necessary details for an agent to correctly invoke and interpret 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?
Input schema coverage is 100% with descriptions for all three parameters. The description adds that only these parameters work and that aggregation defaults to week, but does not provide deeper semantics beyond the schema. 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 time-series data for cloud evaluation-to-paid conversion. It distinguishes its shape from sibling tools (churn/renewal) by specifying flat series structure, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the caller must compute the conversion rate from two series and notes that only aggregation/startDate/endDate work while other filters are ignored. It also covers edge cases like reversed or future-only ranges. While it does not explicitly name alternatives, the shape contrast with churn/renewal implies 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds significant behavioral insights: server cap at 50, unreliability of order=desc, sortBy restrictions, and known contradictions (partnerType upgrade). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, one paragraph with a clear structure: purpose, output format, filter capabilities, key constraint (limit), and a link to documentation. Every sentence adds essential information without 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?
Given 14 parameters, 6 enums, and no output schema, the description covers the main purpose, output fields, and important parameters. It includes a link for full details. However, it does not elaborate on the exact relationship to 'sale metric' or clarify pagination behavior beyond offset/limit.
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 93%, so baseline is 3. The description adds value by noting behavioral quirks (e.g., order=desc unreliable, partnerType upgrade excluded) and providing context on return fields. However, it does not describe each parameter individually 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 returns 'License-event details underlying a sale metric' with specific output fields and mentions the API endpoint. It distinguishes itself as a detailed view under a sale metric, which is distinct from aggregate metrics tools like metrics_churn among siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 does not provide explicit guidance on when to use it versus alternatives (e.g., metrics_details_export, metrics_churn). The usage is implied by the description of detailed events, but no when-not-to-use or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint. Description adds behavioral details: silent ignore of filters, empty result for reversed ranges, and response structure specifics (no uniqueTotal, addons.datasets). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with main purpose first, then details, a note, and a link to spec. Every sentence adds value, though slightly verbose for an experienced user.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description compensates by explaining the response structure (total.datasets, addons, no uniqueTotal) and behavior on invalid inputs. Covers complexity well.
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 value by noting that other filters are ignored and that aggregation affects the number of elements, plus the effect of start/end dates on empty 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 it provides 'Cloud renewal TIME-SERIES' with specific structure (total.datasets split by billing period, two series each), and explicitly contrasts with churn, distinguishing it from sibling tools like metrics_churn.
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 only aggregation/startDate/endDate work, other filters are silently ignored, and that reversed/future ranges return empty. Could further clarify when not to use, but sibling context and description imply it's for renewal metrics.
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, idempotent, non-destructive. Description adds crucial behavioral details: large CSV (~150 MB, binary/octet-stream), presigned URL expires in ~300s, and describes response structure. 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?
Well-organized: purpose, response shape, data details, scope clarification, expiry warning, link to spec. Slightly lengthy but every sentence adds value. Acceptable for a complex tool.
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 fully explains what the tool returns (response shape, CSV columns, expiry). Also clarifies scope and provides API reference. Completely adequate for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100%. Description adds no parameter info but provides complete context on response shape and data columns, which is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a presigned S3 URL for the latest public marketplace app-catalog snapshot. It distinguishes from siblings by specifying it's the whole marketplace, not vendor-specific. The response shape and constraints are clearly outlined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context that this returns public marketplace data (all vendors) and not your own apps or product/pricing structure. Mentions presignedUrl expiry and prompt download. Could explicitly name alternative tools for vendor-specific data, but strong guidelines.
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 provide readOnlyHint, idempotentHint, etc. Description adds: no aggregation, pagination ignored, invalid sourceKey returns HTTP 400, and a link to API spec. This adds meaningful 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 concise, front-loading the core purpose and return format. It includes a link but doesn't waste words. Slightly verbose due to the link, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description explicitly states return format {details:[{searchKeyword, percentage}]}, notes no time series, and flat share. With 3 params (1 required) and high schema coverage, this is complete. URL to spec adds extra completeness.
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 context about sourceKey enum values (marketplace vs embedded-marketplace) and error case, and reinforces startDate/endDate usage. This extra value justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 top search keywords for one source, with specific details (flat keyword share, no time series). It naturally distinguishes from siblings like search_keywords_by_app by focusing on source-level.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (for one source), mentions filters (startDate/endDate, no aggregation), and that pagination is ignored. It lacks explicit exclusions or direct alternative naming, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating safe read-only behavior. The description adds transparency by specifying it is an aggregate and that certain parameters are ignored, which is 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 well-structured, front-loading the purpose and return shape, then detailing filter behavior and linking to the spec. While informative, it could be slightly more concise by omitting the full output shape example.
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 provides a complete return structure. It explains the behavior of all parameters and the aggregate nature, ensuring the agent understands the tool's full capabilities and constraints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds value by explicitly clarifying which parameters are effective (aggregation, startDate, endDate) and which are ignored, providing context not in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns 'Top search keywords across all the partner's apps (developer-space wide).' It specifies the scope ('partner's apps' vs. single app, distinguishing from siblings like search_keywords_by_app) and provides the exact return shape.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions valid filters (aggregation/startDate/endDate) and explicitly states that pagination/productId/hosting are ignored, clarifying correct usage. However, it does not explicitly advise when to use this tool over alternatives like search_keywords_by_app, though the context implies partner-level analysis.
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, idempotentHint, destructiveHint. The description adds valuable behavioral context: timeout override via env variable, return format (JSON array), and error scenario (404 when early). 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 concise sentences plus a link. Front-loaded with essential information, 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 simple input schema and annotations, the description adequately covers purpose, usage, and return type. The only minor gap is parameter details, but overall it is complete enough for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the exportId parameter beyond its role in the tool. It does not specify how to obtain the ID or its expected format, leaving a 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 clearly states 'Download a completed async transactions export' with a specific verb and resource. It distinguishes from sibling tools like transactions_export_async_start and transactions_export_async_status by referencing completion and the status endpoint.
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 instructs to call only after the *_status endpoint reports DONE, else a 404 error is returned. Also mentions the configurable timeout, 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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds value by stating the map is static and loaded from environment variables, clarifying no API call is made.
Agents need to know what a tool does to the world before 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 plus a link, front-loading the core purpose and usage, 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 zero-parameter tool with no output schema, the description fully explains what is returned and its source, and provides context with the related endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, and the schema coverage is trivially 100%. The description adds no parameter info, but baseline 4 applies per rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns a static name->productId map from env vars, and distinguishes itself by noting it's for lookup without an API call, referencing the related apps_list endpoint.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool to look up product UUIDs by friendly name without an API call, and mentions apps_list as the closest related endpoint, providing clear context but no explicit 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive. The description adds key behaviors: return structure, cursor pagination, offset silently ignored, invalid filters return HTTP 400. This significantly supplements 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 three concise sentences plus a link. The main purpose is front-loaded, no redundancy, every sentence adds value (purpose, return structure, pagination, external reference).
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 complexity (8 parameters, many optional) and lack of output schema, the description covers return fields, pagination behavior, error conditions, and includes a link to full spec. It is complete for a read-only list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 88%, so the schema already describes parameters well. The description does not add meaning beyond what's in the schema for individual parameters, so 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 'List versions for an app-software' with specific verb and resource. It distinguishes from sibling tools like app_software_version_get (which gets a single version) and app_software_version_create/update by focusing on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides pagination details (cursor-based, offset ignored) and a link to the spec, but lacks explicit guidance on when to use this tool vs. alternatives. However, since it's the only listing tool for app-software versions, usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), the description adds that HTTP 404 is returned for apps without a migration-compatibility record, which is a key behavioral detail. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences and a spec link, front-loaded with the purpose, then return format and error behavior. No redundant 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 tool with one parameter and clear return structure, the description covers all necessary context including error cases. The spec link covers additional details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description reinforces that productId is a path segment and no query parameters exist, adding clarity beyond the schema's basic 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 verb 'Get' and the resource 'DC-to-Cloud migration compatibility info for an app'. It distinctly differentiates from sibling tools like create/update by focusing on read-only retrieval.
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 return structure and the 404 error condition for missing records, and notes the path segment usage. While it doesn't explicitly state when to use vs alternatives, it's implied for reading, and a spec link 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?
Beyond annotations (readOnly, idempotent, etc.), the description adds the response shape and the fact that certain filters are ignored. It provides context about the data structure and behavior without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two clear paragraphs: purpose with response shape, then filtering behavior and link to spec. No extraneous words, 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 no output schema, the description provides an elaborate response structure example and a spec link. It covers filtering, grouping, and the data shape, making it fully adequate for a read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although schema coverage is 100% with basic descriptions, the description adds value by stating that only startDate/endDate work and that others are ignored, clarifying parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'distribution' and resource 'customer users by edition', clearly distinguishing from sibling 'customer_insights_regions' by noting the grouping. It also states the time granularity 'per month' and the set of editions.
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 specifies that only startDate/endDate filters are effective and that other parameters are ignored, guiding correct use. However, it does not explicitly compare to alternatives like customer_insights_tiers or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and read-only behavior. The description adds return format details and notes HTTP 404 for nonexistent IDs, which is beyond annotation scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences plus a link, front-loaded with the action and resource. No extraneous 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?
For a simple get operation with one parameter, the description provides the return fields, error behavior, and a link to the full spec. No output schema needed as description covers it.
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%. The description reinforces the parameter's purpose with examples (jira, confluence) and notes it comes from parent_software_list, adding context to 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 'Get one parent software... by ID', specifying the verb and resource. It distinguishes from sibling tools like parent_software_list by indicating retrieval by ID, and provides example IDs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (when you have a specific ID) and gives examples. It implies alternatives (e.g., parent_software_list for listing all) but does not explicitly name them 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that the return payload is identical to `search_keywords_by_app`, that the export links are broken, and that data comes inline. Annotations already indicate read-only, idempotent, non-destructive; description adds critical behavioral caveats 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?
Packs essential information (purpose, behavior, broken feature, spec link) into two sentences plus a note. Front-loaded with verb+resource, uses symbols for emphasis, 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 specifies the return structure (`_links`, `summary`, `details`) and addresses the broken export URLs. Includes a reference to the API spec. Covers all relevant aspects for an export 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% coverage with descriptions. The description adds that `productId` is a path segment, but provides no further semantic enrichment for other parameters. Schema already handles parameter meaning adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Export variant of per-app search keywords' and explicitly contrasts with 'search_keywords_by_app', distinguishing it from the sibling tool. Specific verb 'export' and resource 'per-app search keywords' with inline return data description.
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 warns about broken `_links.export` URLs and advises using inline data directly. It implies usage for export scenarios but does not explicitly compare to other export siblings like `search_keywords_by_source_export`. The warning provides important usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate non-readOnly, non-idempotent, and non-destructive. The description adds useful behavioral details: the tool stores the artifact, returns specific fields (fileInfo, _links, details), and maps 'url' to 'uri' for the API. 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 efficiently convey action, return structure, and a key note. Front-loaded with the primary action, no redundant information. Each 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?
With 2 parameters (100% schema coverage), no output schema, and clear annotations, the description provides sufficient context: the action, return shape, a crucial parameter note, and a reference link. No gaps identified.
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 explains the critical mapping from 'url' (accepted by the tool) to 'uri' (API field), which is essential for correct usage. It also hints at the return structure, complementing the schema's full coverage of 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?
Clearly states the tool fetches an artifact from a public URL and stores it, distinguishing it from related tools like artifact_get. The verb 'fetch' and resource 'artifact from a public URL' 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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the primary use case ('fetch an artifact from a public URL and store it'), providing context for when to use this tool. However, it does not explicitly mention when not to use it or suggest alternatives (e.g., artifact_get for retrieval).
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, openWorldHint, idempotentHint, destructiveHint. The description adds behavioral details: usersPercent sums to ~100% per host product, productId/hosting ignored, and the filtering behavior. 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 fairly long but every sentence adds value. It front-loads the key purpose and then details structure and filtering. Could be slightly more concise, but structure is logical.
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 fully explains the return structure (group keys, fields like usersDistribution) and behavior (percentage per host product, date filtering). Also provides a link to the full spec for completeness.
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%. The description adds meaning beyond schema: clarifies product is a name (not UUID), case-insensitive, and that omitting it returns all host products. This reinforces and extends schema 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 'User-tier distribution of your customers, per month, split by HOST PRODUCT' and explains the grouping keys and value fields. This distinguishes it from sibling insights tools (active users, editions, regions).
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 filtering by product (name, case-insensitive), date range, and notes that productId/hosting are ignored. It does not explicitly state when to use this tool vs alternatives, but the context of sibling tools implies distinct purposes.
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 significant behavioral detail beyond the annotations, including the exact output format (flat series without datasets or uniqueTotal), the per-app addons structure, and the behavior of ignored parameters. It also references the API spec for further clarity, fully informing the agent of what to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but packs essential details: purpose, output shape, filter limitations, and a link to the API spec. It is front-loaded with the main purpose. While slightly dense, every sentence adds value with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 parameters, complete schema coverage, and no output schema, the description compensates by explaining the output structure in detail. All parameter behaviors are covered, and the context of ignored filters is provided. No gaps remain for the agent's effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100%, so the description does not need to repeat schema definitions. However, it adds value by listing allowable metric values with error conditions, stating the default for aggregation, and clarifying which parameters are ignored. This contributes to 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 'Evaluation time-series grouped by a dimension' and explains the output structure (FLAT total.series[], per-app addons). It specifies the grouping dimensions from the metric parameter and notes which filters are ignored, making the tool's purpose unambiguous and distinguishing it from other evaluation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on usage by listing the only effective filters (aggregation, startDate, endDate) and noting that productId/hosting/addon are silently ignored. However, it does not explicitly mention when not to use this tool or suggest alternative tools among siblings, so it lacks exclusion 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 indicate read-only, idempotent, non-destructive. Description adds key behavioral details: ~2-3 month lag, large response triggers truncation, filter precedence between addon and productId, silent ignoring of invalid UUIDs. Comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and informative, front-loads main purpose. Slightly long but each sentence adds value. Could be tightened slightly, but effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema but description explains return structure. Covers filter behavior, default response size warning, and data lag. Complete 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 coverage is 100% (baseline 3). Description adds meaningful context: for addon clarifying it's app key not UUID, for productId its undocumented status, and effects of combining filters. Adds significant value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it returns per-app monthly churn benchmark vs. ecosystem average, with detailed response structure. Distinguishes from sibling tools like metrics_churn by focusing on benchmark.
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 on filtering, publication lag, response size concerns, and use of date range. Lacks explicit when-not-to-use or alternatives, but sufficient.
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?
Adds significant behavioral context beyond annotations: describes broken export links, how JSON vs CSV outputs differ, the structure of JSON response, and that invalid accept parameter returns HTTP 400. This is a high-value disclosure that prevents misuse.
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 efficient, front-loading the core purpose and including a crucial warning about broken links. It is slightly long due to the warning and spec URL, but all sentences contribute meaningful 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 no output schema, the description thoroughly explains both output formats (JSON inline payload structure and CSV string). Covers all filters, default behaviors, and error cases. Provides a spec link for further reference. Fulfills all informational needs for an export tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description adds context by noting that 'json' is the default accept option and that invalid values cause an error. It also clarifies the date formats are ISO and that aggregation defaults to 'week'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 is an export variant of partner-wide search keywords. Differentiates from sibling 'search_keywords_partner' by noting the same payload for JSON and the CSV option. Also lists filters (aggregation/startDate/endDate).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: it is for exporting data in JSON or CSV format. Warns about broken `_links.export` URLs, advising to use inline data or CSV instead. Does not explicitly state when to use this tool over alternatives, but the purpose is specific 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?
Annotations already declare readOnly, idempotent, non-destructive. The description adds beyond annotations: reveals cursor pagination (despite the name), describes pagination token usage, and notes that unknown filter values return empty list instead of error. This fully informs the agent of key 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?
Every sentence adds value: return structure, pagination nuance, filter details, and a reference link. No fluff, well-organized, 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.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a paginated list tool with no output schema, the description adequately covers return structure (links, versions with specific fields), pagination mechanism, and filter options. Combined with annotations, an agent has enough to use this 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 coverage is 80% (4 of 5 parameters documented). The description adds context for cursor (pass from links.next) and clarifies filter behavior (narrow at payload level). However, appSoftwareId lacks description in both schema and tool description, slightly reducing 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 lists version-listings for an app-software, enumerating the returned metadata fields (screenshots, highlights, etc.). It distinguishes from siblings like app_version_listing_get (single) and app_version_listing_update by focusing on the list-all 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?
Provides guidance on pagination (cursor-based, default 10/page) and filtering by state and approvalStatus, including edge case behavior for unknown values. Does not explicitly mention when to use alternatives like app_version_listing_get, but gives sufficient context for typical use.
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 read-only, idempotent, non-destructive. Description adds critical quirks: date range silently ignored, CSV missing column, non-existent productId returns 500. 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?
Concise yet thorough: single sentence for purpose, then structured quirks and spec link. No wasted words; every sentence adds needed context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description lists JSON keys and covers quirks comprehensively. Spec link provided. Given complexity of export endpoint, description leaves no critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions. Description adds value by clarifying date behavior (future-dated default), productId usage (narrows export), and accept default. Verified examples further aid 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 'Export Cloud free-starter-tier entitlements' with a specific verb and resource. It differentiates itself from siblings like licenses_export_* by focusing on free-starter-tier and single-date snapshot.
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 on parameter usage (e.g., date is a single snapshot, not range) and warns about quirks (CSV omission, HTTP 500). Could be clearer when to choose this vs other export tools, 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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare read-only, open-world, idempotent, non-destructive. Description adds beyond: 10-minute timeout, large export spill, order=desc unreliability, partnerType exclusion of upgrade. This provides rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly long but well-organized, front-loaded with core purpose and format. Each sentence adds specific value (timeout, spill, parameter quirks). A minor reduction could improve conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description details return formats (CSV columns, JSON array). Covers all 13 parameters thoroughly, includes timeout and spill behavior. For a complex export tool, this is highly 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 100%, but description adds significant context: text is verified, addon is undocumented, order unreliability, accept defaults, sortBy allowed values, partnerType edge case. This exceeds the schema's 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 exports license-event details for a sale metric, specifying CSV or JSON output. It distinguishes from sibling metrics_details_by_metric by noting no offset/limit and full dump. This meets 'specific verb+resource, distinguishes 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 explicitly compares to metrics_details_by_metric, noting the same filters but no pagination, which guides use for full dumps. Lacks explicit when-not-to-use or alternatives list, but context is 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?
Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses that the endpoint can return 5xx errors on large datasets and that refunds appear as negative amounts. It also provides a link to the full spec, enabling detailed behavioral understanding. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and key usage notes. It includes a spec link for further details. While slightly verbose due to the `text` search documentation, it remains focused and every sentence adds essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the high parameter count (19) and no output schema, the description covers the tool's overall purpose, error behavior, and search capabilities. It lacks explicit details about pagination, response structure, or expected output fields, but the spec link partially compensates. Overall, it is reasonably complete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 58%, so the description adds value for under-documented parameters. It elaborates on `text` (search across identifiers), `hosting` (enum casing), `cloudComplianceBoundaries` (applies only to cloud-hosted apps). However, many other parameters like `limit`, `offset`, and `sortBy` are left to the schema and not enriched in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List sales transactions') and the specific resource ('for this vendor's apps'). It also notes that refunds appear as inline negative amounts, providing precise semantic context. It distinguishes this tool from the sibling `transactions_export_async_*` tools for large data pulls.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises against using this tool for large datasets and directs the agent to prefer `transactions_export_async_start` + `status` + `download`. Also explains that the `text` parameter can search by multiple identifiers, giving clear when-to-use 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 read-only, open-world, idempotent, non-destructive. Description adds critical behavioral details: potential slowness, timeout (60s), hanging risk, and deprecation. 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?
Description is well-structured with warning first, then spec link. However, the spec URL is long and could be considered extraneous. Information density is high but every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple list tool with no parameters: provides performance warning, usage guidance, alternative suggestion, and spec reference. No output schema needed as return values are self-evident from action.
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?
Input schema has 0 parameters, so description cannot add meaning beyond schema. However, it explains that the tool lists all promotions without filtering, which is the entire semantic context 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?
Clearly states 'List ALL promotions in one non-paginated response (legacy)', explicit about the scope and legacy status, and distinguishes from the paged sibling tool promotions_list_paged.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to prefer promotions_list_paged in most cases, specifying when to use this tool ('only when you truly need every promotion at once and know the set is small').
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 annotations (readOnly, idempotent, etc.), the description reveals response structure, pagination mechanism differences, and a critical warning about response size exceeding caps and spilling to temp files. This goes beyond what annotations alone 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?
The description is a single, well-organized paragraph that starts with the core purpose, then adds critical guidance, platform specifics, and a caveat. Every sentence adds value; no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 parameters, pagination differences, response size issues), the description covers all essential aspects: purpose, alternative, return format, platform behavior, and a precaution. No output schema, but the return structure is described sufficiently.
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 56%, but the description adds meaningful context about pagination parameters (offset/limit vs nextId/prevId) and advises a modest limit. It does not detail each parameter individually, but the overall guidance compensates well for the gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists promotions with pagination and strongly distinguishes it from the non-paged sibling 'promotions_list' by warning about timeouts. The verb 'list' and resource 'promotions' 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends this tool over 'promotions_list' due to timeout risk. Also explains platform-specific pagination behavior (Cloud vs Server/DC), guiding proper parameter usage.
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:

[![atlassian-marketplace-mcp MCP server](https://glama.ai/mcp/servers/rustem-shiriiazdanov/atlassian-marketplace-mcp/badges/card.svg)](https://glama.ai/mcp/servers/rustem-shiriiazdanov/atlassian-marketplace-mcp)

Score Badge

Copy to your README.md:

[![atlassian-marketplace-mcp MCP server](https://glama.ai/mcp/servers/rustem-shiriiazdanov/atlassian-marketplace-mcp/badges/score.svg)](https://glama.ai/mcp/servers/rustem-shiriiazdanov/atlassian-marketplace-mcp)

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/rustem-shiriiazdanov/atlassian-marketplace-mcp'

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