Heimdall App Store Connect MCP

Server Quality Checklist

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

Latest release: v2.3.0
Disambiguation2/5
With 343 tools covering the entire App Store Connect API, many tools share similar naming patterns for different parent resources (e.g., multiple builds list variants). The descriptions are clear, but the sheer volume increases misselection risk, and machine-generated suffixes like '_0zdb21' make some tools harder to distinguish.
Naming Consistency3/5
The dominant pattern is resource__subresource__action with lowercase snake_case, which is consistent. However, there are notable deviations: meta tools use prefixes like asc__, pricing__, reviews_ai__, and several tools have random alphanumeric suffixes to avoid collisions.
Tool Count1/5
343 tools is an extreme mismatch for a usable MCP server, even for a large API. The guidance suggests 50+ tools is extreme; this is nearly seven times that. The inclusion of search and discovery tools acknowledges the problem but does not fix the cognitive load.
Completeness4/5
The tool set covers a vast range of App Store Connect resources and includes composite helpers plus a search tool for missing operations. Minor gaps exist, such as missing delete for app_clip_advanced_experiences and alternative_distribution_packages, but overall coverage is very high.
Average 3.7/5 across 303 of 343 tools scored. Lowest: 2.7/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 228 commits in the last 12 weeks
- Last stable release on August 25, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI is passing
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
This server has been verified by its author.
View related servers

How to sync the server with GitHub?

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

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

How is the quality score calculated?

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

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

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

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

Tool Scores

Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the description correctly implies a write operation. However, it adds no additional behavioral context such as required permissions, side effects, error conditions, or response details. For a create tool with no output schema, more disclosure would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with one clear sentence and the endpoint. It is front-loaded with the action. However, it could benefit from a brief note on response or typical usage without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (nested required parameters, multiple optional fields) and no output schema, the description is insufficient. It doesn't mention what is returned, validation rules (e.g., locale format), or common failure modes. The agent is underinformed 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 coverage is 100%, but the description only provides a generic reference to the Apple schema. The 'body' parameter's description ('JSON:API request body...') adds no semantic meaning beyond the schema structure. The agent is left to fully interpret the nested required fields without explanatory context about fields like locale, relationships, etc.
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 'Create a beta app localization' with the HTTP method and endpoint. The verb 'Create' and resource 'beta app localization' are specific, and the tool name clearly distinguishes it from CRUD siblings like get, list, delete, 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 guidance on when to use this tool versus alternatives. No prerequisites, when-not-to-use, or comparison with similar tools like beta_app_localizations__get or beta_app_localizations__update. The agent must infer usage from the CRUD pattern alone.
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 are minimal (non-read-only, non-idempotent, non-destructive). The description adds only 'Create', which implies mutation, but nothing about side effects, permissions, or response behavior. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus endpoint), which is concise but lacks structured information. It is not front-loaded with key details, making it minimally adequate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of nested objects and required fields, the description is incomplete. It does not explain the purpose of an alternative distribution package, the required relationships, or any constraints. No output schema exists to compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with the body parameter described in the schema as 'JSON:API request body'. The description adds no additional meaning beyond what the schema provides, achieving the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create) and resource (alternative distribution package) with the HTTP method and endpoint. It distinguishes the resource name from siblings, but does not explicitly differentiate it from other create tools like alternative_distribution_domains__create.
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, prerequisites, or conditions. The description only states the basic operation without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations (readOnlyHint, idempotentHint, destructiveHint) clearly indicate a safe, idempotent, read-only operation, so the bar for description is lower. The description does not contradict these annotations and correctly implies listing. It could add behavioral context about pagination or response size, but the annotations already convey the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and to the point with two sentences. Every word earns its place, and the HTTP endpoint suffix is informative. It is front-loaded and no unnecessary elaboration.
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 is a list operation with 5 parameters, no output schema, and many sibling tools that might be confused, the description is too sparse. It does not explain the return structure, pagination, or common pitfalls like the note about the bundle ID in the filter_app schema description being in the schema but not reiterated in the tool description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the parameter names and their schema descriptions. It does not provide additional usage context or constraints beyond what is in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states it lists beta app review details, but is generic and does not distinguish it from other similarly named tools like 'beta_app_review_details__get' or 'beta_app_review_details__update'. The appendage of the HTTP path is marginally helpful but does not provide a unique scope or verb-resource 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?
There is no guidance on when to use this list tool versus the singular 'get' or the 'update' counterpart. The description lacks any when-to-use or when-not-to-use instructions, and the filter_app parameter is described but not contextualized as a main filter requirement.
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=true, idempotentHint=true, destructiveHint=false, so the agent knows this is a safe read operation. The description adds no behavioral context beyond the endpoint URL, such as pagination behavior, rate limits, or response structure. The added value over annotations is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one sentence plus the endpoint. It front-loads the purpose efficiently. However, it is too brief to be fully informative; a second sentence about typical use or output format would improve it without adding much length.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and many sibling tools, the description is incomplete. It does not explain the return format, how to paginate using 'next_url', or what relationship inclusion ('include') does. The description also fails to differentiate this list from the similar 'apps__beta_license_agreement__get' 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 description coverage is 100%, and the schema descriptions are detailed (e.g., filter_app specifies valid ID format). The tool description does not add any parameter explanations beyond what is already in the schema. With high coverage, a baseline of 3 is appropriate; the description neither improves nor detracts.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List beta license agreements' with a verb and resource. It distinguishes from similar tools like 'beta_license_agreements__get' (single item retrieval) and 'beta_license_agreements__update' (modification) through the use of 'list'. However, it does not elaborate on what a beta license agreement is or how it differs from related list endpoints like 'apps__beta_license_agreement__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?
The description provides no guidance on when to use this tool versus alternatives such as 'beta_license_agreements__get' for a single record, 'apps__beta_license_agreement__get' for a specific app's agreement, or other list tools. There is no mention of prerequisites, typical use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's not readOnly, idempotent, or destructive, but it's a creation. The description mentions 'POST' implying mutation, but no additional behavioral traits (e.g., whether it requires specific permissions, side effects, return value).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and to the point, but could be more informative without being verbose. Includes the HTTP path, which is helpful.
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 nested input schema and no output schema, the description lacks details such as what the tool returns, error conditions, or additional constraints. Incomplete for confident agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'body', and the description adds 'JSON:API request body (Apple schema: BetaRecruitmentCriterionCreateRequest)', which clarifies the format. However, no further details on parameter semantics beyond what schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a beta recruitment criteria' clearly states the verb and resource, and the HTTP method is provided. However, it does not differentiate when to use this over sibling create/update/delete tools, but the name and context suffice.
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 beta_recruitment_criteria__update or delete. No context on prerequisites or typical use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are uninformative (all false), and the description adds no behavioral details beyond stating the operation. It does not disclose side effects, permissions, or behavior beyond the basic creation action.
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 very short (one sentence plus endpoint), which is concise but lacks substance. It frontloads the action and HTTP method, but the brevity sacrifices clarity and completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and minimal annotations, the description fails to provide sufficient context about the resource, its relationship to apps, or what happens after creation. More domain-specific information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the body parameter has a generic description). The schema itself defines the required structure and fields (type, attributes, relationships), so the minimal description adds little. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'marketplace search detail', distinguishing it from sibling tools like delete and update. However, it does not explain what a marketplace search detail is, leaving some ambiguity.
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 does not mention prerequisites, context, or exclusions, relying solely on the tool name and endpoint.
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 description only repeats 'create' which is already obvious from the name. Annotations indicate it is not read-only (readOnlyHint=false) and not destructive (destructiveHint=false), but the description adds no additional behavioral context such as idempotency, side effects, or any constraints like 'declaration must be unique per app and device family'.
Agents need to know what a tool does to the world before 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 the HTTP endpoint. No wasted words. The essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested schema (required relationships, attributes, enums) and the lack of an output schema, the description is insufficient. It does not explain the return value, error conditions, or constraints like 'only one declaration per app and device family'. The agent would need to infer usage from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% (body parameter has a description), but the tool description does not explain the parameters. The schema itself is self-documenting with required fields and enums, so the baseline is 3. The description adds no additional meaning 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?
Description clearly specifies the action ('Create') and resource ('accessibility declaration'). The HTTP method/path provides further context. However, it does not explicitly differentiate from sibling tools like accessibility_declarations__update or accessibility_declarations__delete, though the verb 'create' inherently distinguishes it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., update, delete, or list endpoints). There is no mention of prerequisites, such as requiring an existing app ID or that this declaration can only be created once per app and device family.
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 idempotentHint=true and destructiveHint=false. The description adds only the purpose and API endpoint, without disclosing behavioral details such as whether the operation replaces the existing version, any state requirements, or the response format. Therefore, it adds little behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the API endpoint appended, providing all necessary information without fluff. It is front-loaded with the action verb, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite good schema coverage, the description omits operational context for the mutation, such as what the response will be, whether the previous release version is replaced, and any conditions for the App Store version. Since there is no output schema, this absence leaves the agent with incomplete understanding of the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with id documented as 'ID from the matching list call' and body described as a JSON:API request body. The tool description itself adds no parameter detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Set' and clearly identifies the resource as 'the release with App Store version linked to an App Clip default experience.' The endpoint path reinforces the action. However, it does not explicitly distinguish from the sibling GET tool for the same relationship, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description implies usage for setting the release version, but it does not mention the GET counterpart or any prerequisites or conditions. This lack of contextual guidance leaves the agent to infer usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) but the description adds no behavioral context beyond 'Create'. No disclosure of required permissions, idempotency, or error states. With limited annotations, the description should offer more transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, one sentence plus endpoint, and gets straight to the point. However, it lacks structure like separate usage hints or sections.
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 nested input schema and no output schema, the description is too sparse. It does not explain what the response contains, what triggers a successful creation, or any side effects. The agent would need to infer from the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description does not add meaning beyond the schema; the 'body' parameter is already described as a JSON:API request. No enrichment of parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'app encryption declaration', and the endpoint is appended. It distinguishes from siblings like listing, getting, or creating documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., when to create vs list or get). No prerequisites or when-not-to-use information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, so the description should clarify mutations or side effects. It does not mention any behavioral aspects such as required permissions, relationships, or what happens on success/failure.
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 plus endpoint. It is front-loaded with the action. However, it is somewhat bare, lacking detail without being overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with nested required relationships and no output schema, the description is insufficient. Missing contextual information about the necessity of linking to a betaAppClipInvocation and the expected return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description merely states 'JSON:API request body' and does not add meaning or usage hints for the parameters (e.g., locale, title, relationships).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb (Create) and resource (beta App Clip invocation localization), making the purpose clear. It also includes the REST endpoint. However, it does not explain what an invocation localization is or differentiate it from sibling tools beyond the action verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like beta_app_clip_invocation_localizations__update or delete. No prerequisites, when-not-to-use, or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a write operation (readOnlyHint=false) but provide no details on idempotency or destructiveness. The description adds no behavioral information beyond the bare 'Create', leaving the agent uninformed about side effects or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is clear and to the point. The extra HTTP path is not needed but does not harm 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?
With a complex nested schema and no output schema, the description fails to provide any contextual information about the resource, required relationships, or typical usage. It is insufficient for an agent to fully understand the tool's role.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents all parameters. The description adds no additional parameter semantics, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (Create) and resource (beta build localization), but does not distinguish from siblings like update or delete. The inclusion of the HTTP endpoint adds minor redundancy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as when to create vs update a localization. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent, non-readonly, and non-destructive behavior. The description adds only the PATCH endpoint, which hints at partial updates but does not explicitly state whether it is partial or full replacement, what fields are affected, or any side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy, earning high marks for conciseness. However, it is terse to the point of under-specification, which slightly lowers the structural value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with a nested body and no output schema, the description is too minimal. It lacks factual context about partial update semantics, required fields, prerequisites, or response expectations, making it incomplete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers both parameters with descriptions (id and body). The schema already explains the JSON:API structure and available attributes. The description adds no significant semantic details beyond what the schema provides, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a beta group') and provides the HTTP endpoint. It distinguishes the tool from siblings by the verb 'update' and resource 'beta group', though it doesn't specify what attributes can be updated.
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. The description does not mention prerequisites, such as obtaining the beta group ID from a list call, or that this should be used to modify specific settings. Only the schema's 'id' description hints at needing a matching list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutation (readOnlyHint=false). The description adds no further behavioral details like idempotency, side effects, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the purpose. It could be slightly improved by adding more useful context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested parameter and no output schema. The description does not explain what a build beta notification is or what the response contains, leaving the agent underinformed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes the required 'body' parameter. The description adds no additional meaning 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 it creates a build beta notification with the verb 'Create' and resource name. It is sufficiently specific, though it does not explicitly differentiate from sibling creation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or context for appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's not read-only, not idempotent, not destructive, but the description adds no behavioral context beyond 'create'. No mention of side effects, authorization, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and gets straight to the point. However, it could benefit from a bit more structure, such as mentioning required relationships or the purpose of the pre-order.
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?
Lacks details about return values (no output schema), no explanation of the concept of end app availability preorders, and no differentiation from related tools. For a complex nested schema, more context would help 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?
The schema has 100% coverage with a generic description for the body parameter, but the tool description does not add any meaning about what the body should contain or how parameters are used. It relies entirely on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('end app availability pre order'), and includes the HTTP endpoint. It distinguishes itself from sibling tools, which cover different resources like app_clip_advanced_experiences__create or beta_groups__create.
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_availabilities_v2__create). No prerequisites, context, or exclusions provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral details beyond what the annotations already provide. It doesn't mention pagination behavior, return format, or any constraints, so its value over the readOnlyHint/idempotentHint is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely compact, using two short segments to convey the basic purpose and endpoint. Every word is functional, 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 list tool, the description is underspecified. It fails to clarify global vs. scoped territory listing, pagination via next_url, or the optional fields_territories behavior. The sibling tools that also list territories make this ambiguity more impactful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all three parameters with full coverage, so the description doesn't need to add parameter details. It adds no semantic context beyond the schema, but it doesn't mislead either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List territories') and includes the HTTP endpoint, making the tool's function identifiable. However, it doesn't specify that this is the global list, which could be confused with sibling tools like 'app_tags__territories__list' or 'end_user_license_agreements__territories__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 is provided on when to use this tool versus the sibling territory-listing tools. The description only restates the operation and endpoint, leaving the agent to guess the appropriate 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 are minimal (no hints), and the description adds no behavioral details such as permissions, idempotency, or side effects beyond the verb 'Create'.
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 but front-loaded; could be improved by adding more structure or key details without increasing length significantly.
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 complex nested schema and no output schema, the description lacks contextual information about what a review detail is, required relationships, and expected response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to add much; however, it provides no additional explanation of the parameters beyond what the schema already defines.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('App Clip App Store review detail'), distinguishing it from sibling tools like get and 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 guidance on when to use this tool vs alternatives, no prerequisites or conditions 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 set readOnlyHint to false, idempotentHint to false, and destructiveHint to false, which the description does not contradict (it says 'Create', a non-idempotent write). The description adds no behavioral context beyond the annotations (e.g., no mention of side effects or authentication). With annotations present, the burden is lower, so a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the HTTP method in brackets, which is concise and front-loaded with the verb. It could be slightly more structured by separating the endpoint note, but overall it is efficient and not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a nested input schema and no output schema, the description lacks important context such as prerequisites, the purpose of the mapping detail, and what the response contains. This is insufficient for an agent to fully understand the tool's use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the required nested parameters. The description adds no additional meaning beyond the schema; it does not explain the purpose or usage of the 'body' parameter or its subfields. With high coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create an android to iOS app mapping detail', which is a specific verb and resource, distinguishing it from sibling tools like delete, get, update, and list. However, it does not explain what a mapping detail represents, missing context about its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as when the mapping detail already exists or when to use the update or list operations. The name implies creation, but no explicit usage context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only, non-idempotent, and not destructive (though creation is effectful). The description adds only the HTTP method (POST), providing no additional behavioral context such as required permissions, side effects, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus HTTP method), which is concise. It front-loads the main action, but could be slightly more informative without losing compactness.
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 endpoint with a large nested schema required, the description is insufficient. It lacks explanation of what an App Clip advanced experience is, how to construct the request body, and there is no output schema. More contextual details are needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema itself documents all parameters thoroughly. The description does not add any explanatory value beyond what the schema provides, meeting the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('Create') and the resource ('App Clip advanced experience'). The verb-resource combination distinguishes it from sibling tools like update, get, and 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 guidance on when to use this tool versus alternatives (e.g., when to create vs. update, prerequisites like existence of an app clip). The description merely repeats the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false). The description's 'Create' aligns with this but adds no further behavioral details such as authentication needs, side effects, or response behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence including the HTTP method. Front-loaded with purpose, but could benefit from slightly more context without verbosity.
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 no explanation of return values. Missing context about required relationships (though schema covers it) and possible responses or errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so the schema fully documents the parameters. The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'App Clip default experience', with the HTTP endpoint. It distinguishes from sibling tools like _get, _update, _delete, though it doesn't differentiate from advanced experience creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., advanced experience creation), no prerequisites mentioned, and no context about required relationships.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=true, destructiveHint=false, which already convey that this is a write operation that is safe to retry. The description adds the API endpoint and that it updates the document but provides no additional behavioral context (e.g., that uploaded=true triggers server-side processing, or that checksum is used for verification). 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 one sentence plus an endpoint reference, which is efficient and front-loaded. It earns its place by clearly stating the action and the exact REST operation. 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?
The description is minimal for a nested JSON:API body mutation tool. It does not explain the purpose of 'uploaded' or 'sourceFileChecksum', nor the implications of updating these fields (e.g., marking a document as uploaded). It relies heavily on the schema and annotations, which only partially compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 descriptive parameter names and types. The description adds little beyond the schema, except that the id comes from 'the matching list call', which is useful. However, the meaning of attributes (uploaded, sourceFileChecksum) is not expanded beyond their names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('app encryption declaration document'), and includes the API endpoint. It clearly distinguishes this from other app_encryption_declaration_documents__* tools (create, get) and related 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 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 vs alternatives. It doesn't mention prerequisites, related documents, or contrast with create/get/delete operations. There is no mention of required relationships between this document and an encryption declaration.
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=true, idempotentHint=true, and destuctiveHint=false, and the description ('List') is fully consistent with them — no contradiction. However, the description adds no behavioral context beyond that scope: no pagination behavior, rate limits, auth requirements, or response-size consequences (the 200 KB warning lives in the schema, not the description).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short clauses with zero filler; the verb+resource is front-loaded before the endpoint reference. Every word earns its place, and the endpoint adds useful confirmation of the operation 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?
For a 5-parameter list tool with rich schema descriptions and safety annotations, the definition is adequate. Gaps remain: pagination is only cryptically hinted at via limit/next_url parameter descriptions, and there is no guidance for choosing this tool over app_infos__get. The absence of an output schema is partially mitigated by the description naming the returned resource type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even without parameter info in the description. The description itself says nothing about id, limit, include, next_url, or fields_appInfos; the schema carries all parameter semantics, including enum options and the extra-call cost of omitted includes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('app infos belonging to an app'), making the function immediately clear, and the endpoint reference reinforces the resource hierarchy. It does not explicitly name or contrast sibling tools, but the list-versus-get distinction against app_infos__get is evident from the verb and naming convention.
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 app_infos__get (single record), app_infos__update, or app_infos__age_rating_declaration-style sibling routes. No exclusions are stated and no alternatives are mentioned, so an agent must infer usage from the tool name and endpoint pattern.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral context beyond restating the list/GET action and the endpoint path; it does not mention pagination behavior, response shape, authentication needs, rate limits, or any side effects. There is 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 a single sentence with no redundant wording. The verb and resource are front-loaded, and the endpoint reference is a useful compact addition.
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 read-only list operation with fully documented parameters and safety annotations, the description is minimally adequate. However, it omits pagination context around next_url, provides no output-shape expectations since there is no output schema, and does not explicitly distinguish this app-level tool from the build-level perf metrics sibling. These gaps reduce completeness for an agent choosing between related 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 description coverage is 100%, so the schema already documents all five parameters including id, next_url, and the filter fields. The description contributes only the endpoint's {id} placeholder and the general app scope, which adds little beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the perf power metrics belonging to an app.' It is clear what the tool does and which parent resource it targets. However, it does not explicitly differentiate from the sibling tool builds__perf_power_metrics__list, even though the app-level scope implies the 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?
The description provides no guidance on when to use this tool versus the build-level perf power metrics sibling or any other alternatives. It only states the basic action and resource scope, leaving the agent to infer selection criteria on its own.
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 description adds no behavioral context beyond what annotations already reveal (non-read, non-idempotent, non-destructive). No side effects or authorization needs are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with one sentence and an endpoint. It is front-loaded and efficient, though it could include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested schema and lack of output schema, the description is incomplete. It fails to mention the prerequisite relationship with appStoreReviewDetail or the expected result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the description does not need to add parameter details. Baseline score of 3 is appropriate as the description adds no additional semantic information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'App Store review attachment', which is distinct from sibling tools like delete, get, and 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 guidance is provided on when to use this tool versus alternatives. Prerequisites, such as the need for an existing appStoreReviewDetail, are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a write operation (readOnlyHint=false) that is idempotent and non-destructive. The description adds only the HTTP method (PATCH) and resource path, but provides no additional side-effect context such as whether this replaces an existing default experience, whether the referenced App Clip default experience must already exist, or any validation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus the endpoint, which is concise, front-loaded with the action, and contains no filler. It is appropriately sized for a simple relationship-setting operation, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal to be fully complete. It does not explain what happens when a relationship already exists, any dependencies (e.g., the App Clip default experience must exist), or differentiate itself from closely related sibling tools like the two release_with_app_store_vers_* variants. The lack of an output schema is not compensated by behavioral details, making it under-informative for an agent to confidently select and invoke.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete parameter descriptions, including 'ID from the matching list call' for the id parameter and a structured description for the body (with required data object, id, and type enum). The tool description itself offers no additional clarifying information, so the schema carries the full burden as expected with 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Set' and identifies the exact resource: 'the App Clip default experience linked to an App Store version.' This clearly distinguishes it from the sibling get tool (app_store_versions__app_clip_default_experience__get) and from tools that create/update default experiences themselves. The endpoint further clarifies the relationship action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives, such as whether to create a new default experience first or how it relates to app_clip_default_experiences__release_with_app_store_vers_* tools. There are no mention of prerequisites, exclusions, or when to use the corresponding get tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP method and path, but gives no additional behavioral context such as partial-update semantics, authentication needs, or expected response. There is no contradiction between the description and 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 very short and front-loaded: 'Update an app.' followed by the endpoint. There is no filler. It could be slightly more informative without becoming verbose, but as a concise action statement it is well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a nested JSON:API body, no output schema, and a very large sibling tool set, yet the description only states the endpoint. It does not clarify that the body.data.id must likely match the path id, whether the update is partial or full, what the response contains, or how this tool differs from app_infos__update and app_store_versions__update. These gaps are not filled by the schema or annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'body' documented in the input schema. The description itself adds no parameter-level meaning beyond the endpoint path. This matches the baseline for a tool where the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Update an app' with the endpoint '[PATCH /v1/apps/{id}]'. This clearly identifies the tool as operating on an App object and distinguishes it from list/get operations. However, it does not specify which attributes or aspects of the app are updatable, leaving some ambiguity versus other app-related update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. The description does not mention related tools like apps__get, apps__list, or app_infos__update, nor does it provide any prerequisites or exclusions. The only usage signal is the verb 'Update', which is implied by the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate this is a mutation (readOnlyHint=false) but not destructive or idempotent. The description adds no behavioral context beyond this—no mention of side effects, required permissions, rate limits, or consequences. For a create operation with no output schema, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the REST endpoint, which is concise and front-loaded. It avoids unnecessary words, but the lack of additional structure (e.g., bullet points or examples) limits its usefulness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested input schema, lack of output schema, and minimal annotations, the description is too brief. It does not explain what a beta App Clip invocation is, how to construct the request, or any domain-specific context that would help the agent understand the tool's role among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers the single 'body' parameter completely (100% coverage). However, the description does not explain the meaning of the parameter or its required fields (url, buildBundle, localizations) beyond the schema's brief 'JSON:API request body' note. The description adds no semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and the resource 'beta App Clip invocation', directly matching the tool's name and differentiating it from sibling tools like update, delete, and get. The inclusion of the HTTP endpoint further clarifies the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., when to create vs update or delete a beta App Clip invocation). No prerequisites, context, or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It does not mention idempotency, side effects, permissions, or the need to match the body id with the path id. Annotations already indicate non-readonly and non-destructive, but the description fails to enrich that with any additional useful behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with an endpoint reference, making it easy to parse. It is not bloated, but it lacks extra guidance that could make it more useful. It fits the 'appropriately sized and front-loaded' criterion well.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is an update operation with a nested body and no output schema, but the description provides no context about response formats, validation rules, or how to ensure the body id matches the path id. It also fails to disambiguate from similar update tools like app_store_review_details__update, making it incomplete for complex usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are documented in the schema. The tool description adds no extra meaning about the parameters or their semantics, but the schema already describes the structure and required fields, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and a specific resource ('beta app review detail'), making the tool's purpose immediately clear. It is distinctly different from sibling tools like beta_app_review_details__get or beta_app_review_details__list, and the HTTP method and path add precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It only implies that it is for updating a beta app review detail, without mentioning related operations (e.g., get, list) or any prerequisites beyond the parameter hint 'ID from the matching list call.'
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 annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds only the HTTP method and path, which is an implementation detail rather than behavioral context. It does not disclose consequences like cascade 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?
The description is extremely concise and front-loaded, with two short sentences. Every word conveys essential information without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter delete with annotations covering destructive/idempotent behavior, the description is mostly adequate. However, it lacks context about side effects (e.g., what happens to beta testers) and does not help distinguish from related operations in the extensive sibling list.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter 'id' already has a clear description ('ID from the matching list call'). The tool description adds no parameter-level meaning, but the schema sufficiently documents what is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and resource ('beta group'), and includes the endpoint. It is distinct from siblings because it is the only 'beta_groups__delete' tool, though it does not explicitly call out relationships to related tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The sibling list includes many related operations (e.g., builds__beta_groups__remove, beta_groups__update), but the description gives no context about choosing this delete over others.
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 annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already disclose the safety profile, so the bar is lower. However, the description adds no extra behavioral context, such as pagination, return shape, or relationship handling. It simply restates the operation name.
Agents need to know what a tool does to the world before 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, focused sentence plus the endpoint. It is front-loaded with the verb and resource, contains zero filler, and is appropriately sized for a simple get-by-id tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool and full schema coverage, the description is minimally viable. However, it does not mention what the return value contains, and there is no output schema. The fields_customerReviews enum provides some insight into possible attributes, but the description itself is thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The top-level description adds no parameter semantics beyond what the schema already provides, but the schema adequately documents 'id', 'include', and 'fields_customerReviews' with useful examples and limitations.
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 ('Read one customer review') and scope ('by ID'), which is specific and unambiguous. It distinguishes from list operations by using 'one' and 'by ID', though it does not explicitly mention sibling tools like customer_reviews__response__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 is provided on when to use this tool versus alternatives. The description does not mention that the ID should come from a list call, nor does it distinguish this from other review-related tools. The parameter hint 'ID from the matching list call' appears in the schema but not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate it's a write operation (readOnlyHint=false), but the description adds no further behavioral details such as validation rules, 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 very short (one sentence plus endpoint), which is concise. However, it lacks any structured layout beyond the single sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested required fields (type, attributes, relationships) and no output schema, the description does not provide enough context to understand the full structure or behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so the description doesn't need to explain parameters; it meets the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the action ('Create') and the resource ('end user license agreement'), making the purpose clear and distinct from sibling tools like get, update, 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 guidance is provided on when to use this tool versus alternatives like update or delete. There is no mention of prerequisites, context, or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description simply says 'Create', implying a mutation, but adds no details about constraints, side effects, permissions, or failure modes. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the action and endpoint. No extraneous words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a nested required body and no output schema, the description lacks information about return values, validation rules, duplication handling, or required permissions. It is insufficient to fully guide an agent without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the body parameter is described as a 'JSON:API request body (Apple schema: AlternativeDistributionDomainCreateRequest)'). The tool description adds no further parameter meaning beyond what the schema provides, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('alternative distribution domain'), and includes the HTTP endpoint, making it distinct from sibling tools like alternative_distribution_domains__delete or alternative_distribution_domains__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 is provided on when to use this tool versus alternatives (e.g., why create vs. list or delete). There are no prerequisites, exclusions, or context about when creation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is a write, non-idempotent, non-destructive operation. The description adds no behavioral context beyond what annotations already provide, such as 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: one sentence and the HTTP method. 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?
For a tool with nested objects and no output schema, the description lacks detail on what an alternative distribution key is, the purpose of the fields, or the return value. Incomplete for the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description notes the body is a JSON:API request body following an Apple schema. This adds some context, but does not explain the meaning of fields like 'publicKey'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('alternative distribution key'), distinguishing it from sibling tools like delete, get, and 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, prerequisites, or constraints. The description simply states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the GET endpoint but does not disclose pagination behavior, relationship inclusion, or projection details beyond what the schema already provides. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action and resource, and includes a useful endpoint reference. Every word earns its place with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and the tool has six parameters, the description is too sparse to convey pagination behavior, filtering options, relationship inclusion, or return expectations. The schema helps, but the description does not tie it together for an agent deciding how to invoke and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all six parameters, so the schema carries the semantic load. The description adds no parameter-specific information and does not need to, given the exhaustive schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and resource ('app categories'), and the endpoint [GET /v1/appCategories] reinforces this. It distinguishes from sibling tools like app_categories__get by indicating a list operation, but it does not add detail on scope or filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as app_categories__get or app_categories__subcategories__list. The description only states what the tool does, not the context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description merely repeats the creation action already implied by the tool name and annotations (readOnlyHint=false). It does not disclose any additional behavioral traits, such as whether the image file must be uploaded separately, size limits, or other 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 a single sentence plus the endpoint reference, which is front-loaded with the purpose. There is no extraneous information; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested schema (with required attributes) and lack of output schema, the description is incomplete. It does not explain what the tool returns, any prerequisites (e.g., image upload), or how this relates to other advanced experience 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 100%, so the input schema fully documents the required parameters. The description does not add any parameter-specific details beyond what is already in the schema, resulting in no added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('App Clip advanced experience image'), and includes the HTTP method and endpoint for additional context. It distinguishes itself from siblings like get and update for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to create an image vs. the parent advanced experience. No prerequisites or context for invocation are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it's a write operation (readOnlyHint=false) but add no other behavioral traits. The description only repeats 'Create' from the name, adding no insight into idempotency, side effects, or required permissions beyond what annotations already imply.
Agents need to know what a tool does to the world before 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 immediately states the purpose, followed by the endpoint. No extraneous words; highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with a complex nested body, the description omits critical context: it does not explain that the relationship to an App Clip default experience localization is required, nor does it describe the response format. The tool's purpose is clear, but the context is thin.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully describes the parameters. The description adds no extra meaning about what 'fileName' or 'fileSize' represent or how to obtain them. 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 'Create an App Clip header image,' using a specific verb and resource. It distinguishes this tool from sibling CRUD tools like get, update, delete for the same resource.
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. It does not mention prerequisites (e.g., needing an existing App Clip default experience localization) or when to use update instead.
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?
Description only says 'Create' and endpoint. Annotations are all false, providing no hints. The description adds no behavioral context about idempotency, side effects, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence with endpoint reference. No wasted words, but could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a CRUD tool with a rich schema, but missing context like requirement to link to an appStoreVersion. No output schema, so description could mention expected response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema explains the 'body' parameter structure and includes a description for it. With 100% schema coverage, baseline is 3. The tool description adds no additional parameter context beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (Create) and resource (App Store review detail), and includes the HTTP method and endpoint. It distinguishes from sibling tools like get and 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 guidance on when to use this tool versus alternatives such as update or get. The description does not mention prerequisites like requiring an appStoreVersion relationship.
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=true and idempotentHint=true, so the safety profile is clear. The description adds no additional behavioral traits beyond the endpoint path, such as pagination details, rate limits, or auth requirements. For a read-only operation with full annotation coverage, the description contributes minimal extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 18-word sentence followed by the REST endpoint. Every word earns its place; there is no fluff. It is front-loaded with the purpose.
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 list operation with 8 parameters (including filters for screenshot display type and related localizations) and no output schema, the description is too minimal. It doesn't explain pagination, filter usage, or what the response looks like. The endpoint is given, but the agent would need to infer behavior from parameter names alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all 8 parameters described, so the schema carries the semantic load. The description does not add meaning beyond what's in the schema; it merely restates the idea that the tool lists screenshot sets for a given treatment localization. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List', the resource 'app screenshot sets', and the parent scope 'belonging to an App Store version experiment treatment localization.' This is specific and distinguishes it from sibling tools like app_store_version_localizations__app_screenshot_sets__list, which targets regular localizations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs alternatives, such as other screenshot set listing tools or the many sibling experiment treatments. The description lacks explicit 'when to use' or 'when not to use' context, which is especially needed given the dense sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description only says 'Create', adding no additional behavioral traits like required permissions, idempotency guarantees, or side effects. It fails to disclose any important constraints beyond what is already known.
Agents need to know what a tool does to the world before 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 one sentence plus a URL, extremely concise and front-loaded. 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 tool has a complex nested input schema and no output schema. The description does not explain what a treatment localization is, what happens upon creation, or what the response contains. It is insufficient for an agent to fully understand the tool's role in the broader workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema already documents the required nested structure with attributes (locale) and relationships. The description adds no extra meaning beyond labeling the body as 'JSON:API request body'. It does not explain the purpose of locale or the relationship.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid 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 an App Store version experiment treatment localization' with a specific verb and resource. It distinguishes from siblings like app_store_version_experiment_treatments__create and app_store_version_experiment_treatment_localizations__delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. For instance, it doesn't explain when to create a localization vs. creating a treatment, or vs. getting/deleting a localization. Agents need explicit context to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, consistent with a creation operation. The description adds the HTTP method and that it creates a treatment, but does not disclose additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus the endpoint. It is front-loaded and contains no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects with required relationships) and no output schema, the description is too minimal. It does not explain the relationship requirement or what the response looks like, leaving gaps for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single required parameter 'body'. The description adds no extra meaning beyond the schema. Baseline score of 3 applies as the schema adequately describes the parameter structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'App Store version experiment treatment', and includes the HTTP method and endpoint. However, it does not explicitly distinguish from sibling tools like __get or __update, though the 'Create' verb is distinct enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., needing an existing experiment) or scenarios where update/delete should be used instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal that this is a non-read, potentially destructive operation (readOnlyHint=false, destructiveHint=true). The description adds the context that this is a 'RELEASE-level write', which provides some additional behavioral nuance, but it does not disclose side effects, prerequisites, or what specific state might be affected beyond what the annotation implies.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: one sentence states the action, and one sentence gives the endpoint and risk level. Every word earns its place with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the schema being rich, the description lacks any high-level context about what an App Store version promotion is, when it is needed, or what the operation's success criteria are. With no output schema and a complex nested request body, the description alone would leave an agent under-informed about the business purpose and end result.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the 'body' parameter, including nested relationship details. The description itself adds no parameter-specific semantics, but the schema does the heavy lifting, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create an App Store version promotion', using a specific verb and resource. It does not explicitly distinguish from sibling tools, but the resource name is unique among the long sibling list, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. The phrase 'RELEASE-level write' hints at context but does not explain under what circumstances a promotion should be created, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds only the resource context and endpoint, with no additional behavioral details such as return format or potential errors. It is consistent with annotations, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with an included endpoint for reference. It is concise, though the typo 'statu' for 'status' is a minor flaw that prevents a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read tool with one parameter and strong annotations, but the description does not explain what the cache status response contains or when it is relevant. The sibling ambiguity also leaves a gap. It is minimally viable but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully described in the schema as 'ID from the matching list call', giving 100% coverage. The description itself adds no extra parameter meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads the App Clip domain cache status for a build bundle, with a specific verb and resource. It does not explicitly differentiate from the highly similar sibling 'build_bundles__app_clip_domain_debug_status__get', which prevents a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool vs the analogous debug status tool or other build bundle endpoints. The description only implies usage for retrieving cache status but lacks any context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description merely restates the read-only nature without adding extra behavioral context like authentication requirements, rate limits, or relationship to cache status. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the endpoint included for reference. It contains a minor typo ('statu') but no unnecessary words or redundancy, making it efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation with strong annotations and full schema coverage, the description is adequately complete. It does not elaborate on return format or differentiate from a similar sibling, but the provided information is sufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with the parameter 'id' described as 'ID from the matching list call.' The description adds no parameter-level information beyond this, so the schema carries the full burden, which it does adequately.
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 (Read) and the specific resource (App Clip domain debug status for a build bundle), making the purpose obvious. It does not explicitly distinguish from the similar sibling 'build_bundles__app_clip_domain_cache_status__get', but the resource name itself differentiates sufficiently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as the cache status sibling, or any prerequisites beyond the id. The description only states what it does, not when to prefer it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds no additional behavioral context beyond the read action—no auth requirements, pagination details, or return behavior are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains zero waste. It states the action, resource, and endpoint efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with strong annotations and fully documented parameters, the description is adequate for invocation. It does not explain how it differs from the similar customer_review_responses__get sibling, but the structured fields and endpoint make it complete enough for a basic read.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters clearly documented in the schema (id from matching list call, include for relationships). The description adds no parameter detail beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Read the response for a customer review', and includes the endpoint. It distinguishes this from the general customer reviews list/get tools, though it does not explicitly differentiate from the similarly named customer_review_responses__get sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as customer_review_responses__get or the create/delete response tools. The endpoint is shown but there is no explicit context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read, non-idempotent, non-destructive operation. The description adds 'Create' which matches, but does not disclose any additional behavioral traits like required permissions or side effects beyond what annotations imply.
Agents need to know what a tool does to the world before 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 plus endpoint reference, which is highly concise and front-loaded with the key action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the input schema (nested objects with required attributes and relationships) and lack of output schema, the description is too minimal. It does not explain what a routing app coverage is or the implications of creation.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% per context, so the baseline is 3. The description adds a brief note about the request body type but does not explain the meaning of individual nested fields (e.g., fileName, fileSize, appStoreVersion).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'routing app coverage', and includes the endpoint. This distinguishes it from sibling tools like get, update, and delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as when a routing app coverage should be created or what prerequisites exist.
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=false, idempotentHint=true, and destructiveHint=false, so the description adds little beyond the HTTP method. It does not clarify partial update semantics, return value, or side effects. The endpoint path is useful but not a behavioral trait.
Agents need to know what a tool does to the world before 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, direct sentence with the endpoint included. Every word is functional, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no output schema, the description should provide more context, such as what fields are updatable, that it's a partial update, or what the response contains. It relies entirely on the schema and annotations, which leaves gaps for an agent selecting the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both id and body have detailed descriptions, and nested attributes are documented. The description itself adds no parameter-level meaning, so the 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?
The description uses a specific verb ('Update') and a specific resource ('a territory availability'), clearly distinguishing this from list/get/delete tools for related resources. It also includes the HTTP method and endpoint, which reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. It does not mention prerequisites (e.g., obtaining an ID via a list call) or contrast with related availability tools like app_availabilities_v2__territory_availabilities__list. The only usage hint ('ID from the matching list call') is in the schema, not the description.
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=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context beyond the endpoint and the verb 'Read,' which is consistent with the annotations. No rate limits, auth requirements, or error behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that includes the HTTP method and path. It contains no unnecessary words or repetition, making it highly efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple nature of a read operation and the absence of an output schema, the description is minimal but adequate for basic purpose. However, it does not explain the return format or explicitly guide the agent to use the list call first (though the schema's id field description does). Annotations cover safety, so the brevity is partly acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage. The 'id' field is described as 'ID from the matching list call' and the 'fields' parameter includes an enum and explanation. The tool description only adds 'by ID,' which is redundant with the schema, so it does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read'), the resource ('alternative distribution domain'), and the scope ('by ID'). It also includes the HTTP method and endpoint, which distinguishes it from sibling tools like alternative_distribution_domains__list and create/delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It implies single-resource retrieval but does not mention that the ID typically comes from a list call or that listing should be used when multiple domains are needed. No exclusions or alternative tool names are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is not read-only, not idempotent, and not destructive, but the description adds no additional behavioral context. It does not mention idempotency implications, authentication requirements, or consequences of duplicate creation.
Agents need to know what a tool does to the world before 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 stating purpose and endpoint. Every word is essential, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with no output schema, the description covers the basic purpose and endpoint. However, it omits typical additional context like response behavior or relationship constraints, making it moderately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already describes all parameters. The description does not add extra meaning beyond what the schema provides, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create an App Clip default experience localization' with the exact HTTP POST endpoint. This clearly identifies the action and resource, distinguishing it from siblings like delete, get, or 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?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, required relationships, or scenarios where other tools (e.g., app_clip_default_experience_localizations__update) might be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint and destructiveHint, so the description adds the HTTP method PATCH but little else. It does not disclose whether the update is partial/full replacement, permission requirements, or side effects 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?
The description is two concise sentences, with no redundant information. The first sentence states the action, and the second gives the endpoint, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with schema and annotations, provides a functional picture: it updates a localization via PATCH, with only subtitle as an editable attribute (from schema). However, it does not mention expected return values or any caveats, which would be useful given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the 'id' and 'body' parameters, including that 'id' comes from a matching list call and the body structure. The description adds no additional parameter context, 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 the tool updates an App Clip default experience localization, with a specific verb and resource. It distinguishes from sibling tools for create/delete/get on the same resource, and the PATCH endpoint adds specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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/delete, or prerequisites. The verb 'Update' implies modifying an existing localization, but no context is given for when this is appropriate versus other related 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?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the endpoint path but no extra behavioral context such as return format, response size, or any specific side effects. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by the endpoint URL. There is zero wasted text, and the essential information is front-loaded. It is appropriately minimal for a simple read operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity, the presence of safety annotations, and full schema coverage, the description is minimally viable but leaves gaps. It does not explain what the response contains or when to use the include parameter beyond what the schema already states. The existence of a very similar sibling tool is not addressed, so the agent may struggle to choose correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for both parameters (id and include), each with a description. The description itself adds no parameter details, so it does not go beyond the schema. Baseline 3 is appropriate since the schema already documents the parameters thoroughly.
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 ('Read the release with App Store version') and the resource ('App Clip default experience'), with the exact endpoint URL providing additional specificity. However, it does not explicitly differentiate itself from the nearly identical sibling tool 'app_clip_default_experiences__release_with_app_store_vers_0zdbim', so it misses the full 'distinguishes from siblings' criterion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. There is no mention of prerequisites, use cases, or situations where a different tool would be more appropriate. The description simply states the operation without contextualizing it among the many related App Clip tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the GET method but provides no additional behavioral context, such as the ability to include relationships or the potential for large responses. This is minimal added value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the action and resource. It avoids redundancy and contains no filler, earning full marks for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a get-by-ID tool and the presence of full schema coverage and safety annotations, the description is minimally viable but lacks guidance on optional relationship inclusion (include) and field selection (fields). It does not explain when to prefer this over sibling tools, making it adequate but not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not mention parameters, but schema description coverage is 100%, with each parameter (id, include, fields_appEncryptionDeclarations) documented in the input schema. The optional include and fields parameters already have meaningful descriptions in the schema, so the 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?
The description states a specific action ('Read') and resource ('app encryption declaration') with an ID parameter, clearly distinguishing it from list operations. Including the exact endpoint [GET /v1/appEncryptionDeclarations/{id}] reinforces the resource and method.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as app_encryption_declarations__list or the related document getter. The context signals show sibling tools but the description does not mention them or any selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds only the HTTP endpoint and 'Read', without disclosing response format, error behavior, or authentication needs.
Agents need to know what a tool does to the world before 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 sentence plus the endpoint, with no unnecessary content. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read, but there is no output schema and the description does not clarify the response shape or how primary_category differs from subcategory siblings. The endpoint and params are clear, but usage guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both id and include, so the baseline is 3. The description adds no parameter details; the schema itself explains that include is a comma-separated list of relationships to include.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read the primary category for an app info' with a specific verb and resource, and the endpoint confirms the scope. This distinguishes it from siblings like app_infos__secondary_category__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?
There is no guidance on when to use this tool versus related category tools, nor any mention of the include parameter or how to decide whether to fetch subcategories/parent. The description provides no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the readOnlyHint, idempotentHint, and destructiveHint annotations already provide. It does not disclose what happens when the relationship is unset, whether special permissions are required, or any other runtime behavior. The description is consistent with the annotations, so there is no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and resource, then includes the endpoint for reference. It is concise and free of redundant information, with every word contributing value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and the annotations cover safety, but the description lacks context about what 'primary subcategory one' represents in the App Store Connect domain and how it differs from other category/subcategory relationships. The optional include parameter is documented only in the schema, not in the description, leaving a moderate gap in guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for both parameters (id and include), so schema coverage is 100%. The description adds no additional meaning or context about these parameters, thereby meeting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('the primary subcategory one for an app info'). This precise wording distinguishes it from sibling tools such as primary_subcategory_two or secondary_subcategory_one, and the endpoint format is also provided for unambiguous reference.
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, any prerequisites, or exclusions. The schema documents parameters, but the description gives no context on typical use cases or when the 'include' parameter should be used.
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, and destructiveHint=false, so the safety profile is fully covered. The description adds minimal behavioral context beyond confirming this is a GET scoped to an app; it does not disclose pagination behavior or the large-response concern hinted at in the schema. 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?
A single sentence that states the purpose and the endpoint with zero filler. The endpoint reference is immediately useful for confirming the operation shape, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with strong annotations and a fully documented schema, the description is adequate but thin. It omits the pagination behavior (limit/next_url), the filtering options (filter_state, filter_deviceFamily), and the 200 KB payload warning present in the schema, all of which would help an agent invoke it efficiently on large result sets.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all six parameters (id, limit, next_url, filter_state, filter_deviceFamily, fields_accessibilityDeclarations) are already documented in the schema. The description adds no parameter-specific meaning, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('List ... accessibility declarations') and scopes it to a specific app, reinforced by the endpoint '[GET /v1/apps/{id}/accessibilityDeclarations]'. It is obviously the list counterpart to the accessibility_declarations__create/get/update/delete siblings. However, it doesn't go beyond the name to explain what an accessibility declaration is, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to choose this list tool versus accessibility_declarations__get, or on when the filters should be used. The only usage signal is the embedded endpoint, which implies an app id is required. No exclusions, prerequisites, or alternative tools 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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minor context (the exact REST endpoint and the v2 version marker) but discloses nothing about response shape, pagination, or other behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste. The primary verb and resource are front-loaded, and the endpoint reference is a compact, high-value addition that confirms the HTTP operation and path.
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?
Adequate for a simple read operation whose annotations and schema cover safety and parameters, and where the endpoint implies the return type. However, it is incomplete regarding sibling disambiguation — the existence of `app_availabilities_v2__get` is a real ambiguity that the description does not resolve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters, including the useful note on `include` avoiding extra calls. The description adds no parameter meaning beyond the endpoint's `{id}` placeholder, which merely mirrors the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Read') and resource ('app availability (v2) for an app'), and the endpoint path adds concrete specificity. However, it does not differentiate itself from the near-identical sibling `app_availabilities_v2__get`, so an agent cannot easily tell which of the two to select without further investigation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. Given siblings like `app_availabilities_v2__get`, `app_availabilities_v2__create`, and `app_availabilities_v2__territory_availabilities__list`, the absence of any routing hints or exclusions leaves the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds the GET endpoint path and confirms a read operation, but does not disclose response format or edge cases like a missing Game Center detail. This is adequate given the annotations, but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence plus endpoint, with no filler or redundancy. It front-loads the action and resource, and every word contributes to understanding.
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?
This is a simple read tool with two parameters and no output schema. Annotations cover safety and the schema covers parameters. However, the description does not clarify what the Game Center detail object contains or any caveats (e.g., what happens if no Game Center detail is set), so it is minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'id' and 'include' have descriptive text, and the include parameter's behavior (comma-separated relationships, extra call cost) is fully explained in the schema. The tool description itself adds no parameter-level meaning, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'Game Center detail for an app,' and includes the exact endpoint path. It does not explicitly name sibling tools or differentiate them, but the resource is specific enough to distinguish it from other apps__* read tools like apps__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 is provided on when to use this tool versus alternatives, such as apps__get, app_store_versions__game_center_app_version__get, or the many other apps__* siblings. The description only states the operation, leaving tool selection entirely to the agent's 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, and destructiveHint=false, so the safety profile is fully covered. The description's 'List' verb and '[GET ...]' endpoint are consistent with these annotations and add the app-scoping detail, but it discloses no further behavioral context such as pagination behavior or large response sizes (which the schema hints at via the 200 KB note on the fields parameter). No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence followed by the endpoint reference with zero filler or redundancy. The action is front-loaded, and the definition is appropriately sized given that the schema and annotations already carry the parameter and safety details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, idempotent list endpoint whose parameters are fully documented in the schema, the definition is nearly sufficient. The real gap is that the similarly named sibling pre_release_versions__list exists with no stated distinction, and since there is no output schema, the description gives no hint about the response shape. It is minimally viable but leaves sibling ambiguity unresolved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema richly documents all four parameters: id accepts 'App name, bundle ID (com.example.app) or numeric Apple ID', limit is 'maximum resources per page', next_url is a pagination link, and fields_preReleaseVersions has an enum plus a 200 KB row-size warning. The description adds no parameter-level meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a specific resource ('pre release versions'), and a scoping qualifier ('belonging to an app'), reinforced by the endpoint path [GET /v1/apps/{id}/preReleaseVersions]. It is clear about what the tool does, but it does not explicitly differentiate itself from the nearly identical sibling pre_release_versions__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 is given about when to use this tool versus alternatives. The sibling set contains several overlapping tools (pre_release_versions__list, pre_release_versions__get, pre_release_versions__app__get, pre_release_versions__builds__list), yet the description names none of them and provides no exclusion conditions or selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds the explicit GET endpoint but does not disclose pagination behavior, filter semantics, or response shape. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight, front-loaded sentence plus the endpoint path, with no redundant wording. Every element contributes meaning for a simple list operation.
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 read-only list with full parameter schema and safety annotations, this is mostly complete. However, it does not differentiate itself from the semantically similar app_store_version_localizations__search_keywords__list sibling, and with no output schema, a bit more context about the returned keyword data would help.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 useful descriptions for id, limit, next_url, filter_locale, and filter_platform. The description itself adds no parameter-level detail, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('search keywords belonging to an app'), and includes the endpoint template. It is clear enough to identify the app-level list operation, though it does not explicitly contrast with the similar app_store_version_localizations__search_keywords__list sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided about when to use this tool versus the similar app_store_version_localizations__search_keywords__list sibling. The phrase 'belonging to an app' only weakly implies app-level scope and 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?
The annotations already indicate this is a non-read-only, idempotent, non-destructive operation. The description adds the PATCH method and URL path, which is useful context, but doesn't disclose behavior such as partial update semantics, error conditions, or whether the server returns the updated resource. With annotations covering the safety profile, the description contributes modest additional context, warranting a 3.
Agents need to know what a tool does to the world before 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, direct sentence with the endpoint in brackets. It is front-loaded with the action and resource, and every word adds value. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool, the description provides the core action and endpoint, and the schema covers parameters. However, there is no output schema and the description does not state what the response will be or any side effects. Given the minimal complexity, this is adequate but not complete, so a 3 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters described. The description itself adds no parameter details; it leverages the schema entirely. Thus, it meets the baseline of 3 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?
The description clearly states the action ('Update') and resource ('beta App Clip invocation localization'), and includes the HTTP endpoint. However, it doesn't explicitly differentiate from sibling update tools (e.g., beta_app_clip_invocation_localizations__create or delete) beyond the resource name, so it stops short of a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool vs alternatives. The description does not mention prerequisites, that create should be used for new localizations, or that delete is for removal. It only provides the verb and endpoint, leaving the agent to infer usage from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the destructive nature is covered. The description adds only the endpoint and repeats 'unlink'; it does not disclose side effects, authorization needs, or the effect on the beta tester's access. No additional behavioral context is provided beyond what annotations and schema already offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence followed by the endpoint. No redundant information, every word earns its place. It is appropriately sized for the operation.
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 straightforward, and the schema + annotations cover the mechanics and safety. However, the description does not mention that the body must specify which builds to unlink, nor does it clarify applicability versus sibling remove tools. It is minimally complete but leaves room for ambiguity in complex use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id parameter described as 'ID from the matching list call' and the body as the JSON:API request body. The tool description adds no extra parameter semantics, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Unlink' with the resource 'builds' and subject 'beta tester', clearly stating the action. It also includes the exact endpoint, which distinguishes it from sibling operations like beta_testers__builds__add or builds__individual_testers__remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or related tools such as beta_testers__builds__add or builds__individual_testers__remove. The action is implied but no explicit context is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are minimal (all false). Description adds that it's a POST request creating a new tester, but does not disclose behavior on duplicate emails, side effects, or results. Additional context could improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence plus API path. No redundant information. Front-loaded with essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested schema and lack of output schema, the description is adequate but incomplete. It does not mention return value, error handling, or prerequisites, which are helpful for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully defined. The description highlights email and beta groups but omits firstName, lastName, and builds, adding only partial semantic 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 it invites a new tester by email and adds them to beta groups. It specifies the action and resource, but does not explicitly distinguish from siblings like beta_testers__beta_groups__add or beta_tester_invitations__create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as beta_testers__beta_groups__add for existing testers or beta_tester_invitations__create. No context on prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations present (idempotentHint=true, destructiveHint=false), the description adds only the HTTP method and endpoint, which are not truly behavioral traits. It does not disclose side effects, permission requirements, or what fields are affected beyond the schema, offering minimal added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus the API endpoint. Every element is purposeful, with no redundancy or filler, making it highly scannable 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?
Although the schema and annotations provide substantial detail, the description itself is minimal. It does not explain what fields can be updated (e.g., autoNotifyEnabled) or when to use this tool, leaving some reliance on the schema and sibling names for full context. It is minimally viable but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with clear descriptions for the two parameters, including the nested body structure and the id field's origin. The tool description adds no additional parameter context, so the 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?
The description clearly states the action ('Update') and the resource ('a build beta detail'), which is specific and distinct from sibling tools like get or list. The API path [PATCH /v1/buildBetaDetails/{id}] further reinforces the precise scope of the tool.
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 builds__update or build_beta_details__get. It does not mention prerequisites, exclusions, or selection criteria, leaving the agent without strategic 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 indicate this is a non-destructive mutation (readOnlyHint=false, destructiveHint=false). The description confirms 'Create' but adds no additional behavioral context such as side effects or rate limits. No contradiction with annotations, but no added value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise with two short statements. It is front-loaded with the action and resource. However, it may be too brief for a creation tool; a bit more context about the role of a build upload file would improve it.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested schema and the lack of an output schema, the description provides minimal context. It does not explain how this tool fits into the build upload workflow, how to obtain the required buildUpload relationship ID, or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 100% for the single 'body' parameter, which is described as a JSON:API request body. However, the description does not elaborate on the nested required fields (fileName, fileSize, etc.) that are only in the schema. Baseline score applies since coverage is high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Create' and the resource 'a build upload file', distinguishing it from sibling tools like build_upload_files__get or build_uploads__create. Including the HTTP endpoint further clarifies the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. There is no information on when to use this tool versus alternatives, prerequisites (e.g., the need for an existing buildUpload ID), or context about the multi-step upload process.
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 description adds no behavioral context beyond what annotations already provide. Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false; the description merely restates 'Read' without disclosing error handling, response format, or other behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by the HTTP path. It is front-loaded and contains no unnecessary information, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read-by-ID operation, and the schema plus annotations cover the basics. However, the description does not clarify how it differs from related tools like the app-specific EULA getter, and there is no output schema or mention of return details, leaving some ambiguity for the 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 fully documents all three parameters. The description adds no additional parameter semantics, but the baseline is 3 due to 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 the action ('Read'), the resource ('end user license agreement'), and the scope ('by ID'). It distinguishes itself from sibling tools like create/update/delete by naming the read operation explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as apps__end_user_license_agreement__get or end_user_license_agreements__territories__list. It only states the basic function without any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds no additional behavioral context beyond the verb 'Delete' and the HTTP endpoint. It does not mention that deletion is permanent or irreversible, nor any side effects (e.g., related data being removed).
Agents need to know what a tool does to the world before 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, front-loaded sentence that immediately conveys the operation. It efficiently includes the REST endpoint without wasting 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 delete operation with one parameter and full schema coverage, the description plus annotations are sufficient. The agent knows it's destructive (via annotations), what parameter to supply (via schema), and the endpoint (via description). It's missing only minor context like destructiveness wording, but the annotations cover that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the 'id' parameter is described as 'ID from the matching list call.' The tool description itself adds no additional parameter detail, so the baseline of 3 applies since the schema already carries the semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an accessibility declaration,' which is a specific verb+resource combination that distinguishes this tool from its siblings (create, get, update, list). The endpoint is also provided for clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It doesn't mention that this permanently removes the declaration or that the ID should come from a list call (though the schema does). There is no mention of when not to use it or any prerequisites beyond the parameter description.
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 state readOnlyHint=false, idempotentHint=true, and destructiveHint=false, and the description does not contradict them. The PATCH endpoint adds minimal behavioral context (e.g., partial update semantics) but does not disclose auth, response shape, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus endpoint, highly efficient and front-loaded. It could include slightly more context without bloat, but it does not waste words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the very complex nested body schema, the minimal description relies heavily on the schema and annotations. It lacks guidance on update scope, relationships, or when an update is appropriate, but the schema is exhaustive and annotations cover safety, making it minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters (id and body) have descriptions in the schema, with id noting it comes from a list call and body describing the JSON:API request. The tool description itself adds no parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('App Clip advanced experience'), and the PATCH endpoint reinforces the update verb. This distinguishes it from sibling create and get operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus app_clip_advanced_experiences__create or app_clip_advanced_experiences__get. The only implicit signal is the PATCH method, which is insufficient for establishing usage exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds no extra behavioral context beyond restating the delete operation, such as irreversibility, permissions, or side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the purpose and includes the endpoint. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and strong annotations, the description is adequate. It covers the essential operation and resource, though it could note that deletion is permanent, but this is implied by the destructiveHint annotation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description for the only parameter, 'id', is 'ID from the matching list call,' which provides 100% coverage. The description itself does not add parameter details, but the baseline of 3 applies due to full 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 action ('Delete') and the specific resource ('App Clip default experience localization'), with the HTTP endpoint confirming the operation. This is a specific verb+resource pairing that distinguishes it from sibling tools like update, get, or create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool vs. alternatives, or any prerequisites/exclusions. The usage is only implied by the verb 'Delete' and the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description explicitly says 'Create', confirming mutation. However, no additional behavioral traits like authentication needs or rate limits are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence plus the endpoint URL. No redundancy, front-loaded with key action.
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 return value is unspecified. The description does not explain the creation workflow or how this tool fits with others (e.g., subsequent upload steps). Limited context for an agent to understand the full 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?
Schema coverage is 100% with a helpful description: 'JSON:API request body (Apple schema: AppEncryptionDeclarationDocumentCreateRequest).' The tool description adds the endpoint path but no further parameter meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create an app encryption declaration document', which is a specific verb-noun pair. It distinguishes from sibling tools like app_encryption_declaration_documents__get and app_encryption_declaration_documents__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 guidance on when to use this tool versus alternatives (e.g., prerequisites like having an app encryption declaration). The description only states the action, leaving agents to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds only 'by ID', which is already covered by the schema. No additional behavioral context such as response format, rate limits, or relationship expansion effects is provided, so it adds little beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with an endpoint reference. It is front-loaded with the primary purpose and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description plus schema covers the essential information. The include and fields parameters for controlling response content are documented in the schema. The lack of an output schema is somewhat mitigated by the clear resource type from the name and endpoint. A minor gap is the absence of any statement about the returned resource shape, but overall it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: all three parameters (id, include, fields_appInfoLocalizations) have descriptions. The tool description itself adds no parameter semantics, so it meets the baseline but does not enhance understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Read one app info localization by ID', which clearly specifies the action (read), the resource (app info localization), and the scope (by ID). The endpoint [GET /v1/appInfoLocalizations/{id}] reinforces the purpose and distinguishes it from create/update/delete/list 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?
The description gives no explicit guidance on when to use this tool vs alternatives. The only hint is in the id parameter description ('ID from the matching list call'), which is not part of the main tool description. No exclusions or alternative tool names are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/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 the endpoint and confirms a read operation, but provides no extra behavioral context such as response format, permissions, or side effects. It is consistent but not enriching.
Agents need to know what a tool does to the world before 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 followed by the endpoint. Every word earns its place, and there is no superfluous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with full schema coverage and appropriate annotations, the description is mostly complete. However, it lacks any explanation of what the returned resource looks like or how to leverage the include parameter, though the schema does document include. Overall, it is adequate for the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description covers both parameters (id and include) at 100%, so the description doesn't need to add parameter details. It does not, but the baseline of 3 applies because the schema already carries the burden.
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 reads a specific resource: 'the primary subcategory two for an app info.' It uses a specific verb and resource, but does not explicitly distinguish it from sibling tools like primary_subcategory_one or secondary_subcategory_two, although the name itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, and no mention of exclusions or prerequisites. The description simply states what it does without contextualizing its usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint, idempotentHint, and destructiveHint, the description adds no behavioral context beyond the resource path. It does not disclose what happens if no secondary category exists, or the response structure, and thus provides little extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by the endpoint path. It is concise, front-loaded, and contains no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter, the description is adequate: it names the resource and endpoint, while schema and annotations cover parameters and safety. It lacks usage context and return-value details, but given the simplicity of the tool, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters already described. The tool description itself adds no parameter-level details, so the 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?
The description clearly states the action ('Read') and the resource ('secondary category for an app info'), and the endpoint path provides exact API context. It distinguishes from sibling tools like app_infos__primary_category__get and app_infos__secondary_subcategory_one__get by specifying 'secondary category'.
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 usage guidance is provided. The description does not explain when to choose this tool over alternatives such as primary category or subcategory fetchers, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint, idempotentHint, and destructiveHint annotations fully cover the safety profile, and the 'Read' verb plus GET method are consistent with those annotations. The description adds no extra behavioral detail such as authentication or return behavior, but nothing contradicts 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 a single concise sentence with the endpoint reference, and it front-loads the core action and resource. There is no filler, repetition, or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read operation with strong annotations, the definition is largely self-sufficient. The main missing piece is a note distinguishing it from the similar alternative_distribution_keys__get sibling, and a brief indication of what the response contains would be helpful without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents the single required parameter, id, including acceptable formats like app name, bundle ID, or numeric Apple ID. The description adds no parameter-specific detail, but with 100% schema coverage the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific operation: read an app's alternative distribution key, and includes the exact GET endpoint. It clearly separates this from creation, deletion, and update siblings, though it does not explicitly differentiate it from the similarly named alternative_distribution_keys__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?
There is no guidance about when to use this tool versus alternatives like alternative_distribution_keys__get or alternative_distribution_keys__list. The only implicit signal is 'for an app' and the {id} path parameter, which is not enough given the large number of similar sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only 'belonging to an app' and the GET endpoint, which are more about purpose than behavioral traits. It does not disclose pagination behavior, response characteristics, or any other operational context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the verb and resource, followed by the endpoint for clarity. There is no redundant or filler content, and every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The combination of the concise description, 100% schema coverage, and read-only/idempotent annotations provides enough context for an agent to call this simple list endpoint correctly. It could optionally mention pagination flow or the shape of the response, but the schema already documents limit and next_url, so the missing detail is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all four parameters including the optional fields behavior. The description adds no additional parameter meaning beyond implying that 'id' identifies the app, which is already captured in the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('android to iOS app mapping details belonging to an app'), which is unambiguous. It does not explicitly differentiate itself from the sibling get tool, but the 'list' wording and 'belonging to an app' scope make the core 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 implies usage through 'belonging to an app' and the endpoint path, but it does not explicitly state when to use this list operation versus the sibling create/get/update/delete tools. No exclusions or alternative routing guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the resource scope and endpoint but nothing beyond that — no mention of pagination, rate limits, or response characteristics. However, the schema documents the paging parameters (limit, next_url), so the burden is partially shared. 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?
One compact sentence plus endpoint reference, with the purpose front-loaded before the HTTP path. Zero filler words, no repetition of schema content, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with fully self-documenting parameters and annotations that cover safety, little is missing. The response shape is inferable from the pagination and field-selection parameters. Minor gap: the description does not explicitly explain pagina behavior, but the limit/next_url/fields parameters in the schema communicate this adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all six parameters are already documented with meaningful descriptions (e.g., id accepts app name, bundle ID, or numeric Apple ID; include lists relationship options). The description itself adds no parameter-level meaning, but per the rubric, baseline 3 applies when the schema carries the full load.
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?
States a specific verb ('List') with a specific resource ('app custom product pages') and scope ('belonging to an app'). The endpoint reference [GET /v1/apps/{id}/appCustomProductPages] confirms the exact resource path. It doesn't explicitly differentiate from the many sibling list tools, but the resource is named unambiguously enough that an agent can identify what it operates on.
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. With dozens of sibling list tools (apps__app_store_versions__list, apps__builds__list, apps__app_infos__list, etc.), the description provides no selection criteria, no exclusions, and no mention of when a different listing endpoint would be appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds only the endpoint and scope, with no additional behavioral context such as pagination behavior, default sort, or relationship to other resources.
Agents need to know what a tool does to the world before 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 efficient sentence that front-loads the action and resource, followed by the exact endpoint. Every word earns its place and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description plus schema and annotations are largely sufficient: the agent knows the required parameter, the scope, and the safety profile. The main gap is lack of output/return guidance, but that is partially mitigated by the absence of an output schema and the clarity of the 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 description coverage is 100%, so all parameters (`id`, `limit`, `next_url`, `fields_betaAppLocalizations`) are already documented in the schema. The description does not add extra semantics beyond identifying `id` as the app identifier, but it also does not need to because the schema is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a specific resource ('beta app localizations') scoped to an app, and includes the exact REST endpoint. The phrase 'belonging to an app' distinguishes this from the more general sibling `beta_app_localizations__list`, so an agent can tell what this tool targets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance about when to use this tool versus the near-sibling `beta_app_localizations__list`, `beta_app_localizations__get`, or other localization list tools. The scope is implied, but the description does not mention alternatives or exclusionary conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context like the REST endpoint and that '-createdDate' returns the newest reviews, but it does not disclose pagination, default fields, or payload size considerations. 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 a single front-loaded sentence followed by the endpoint. It communicates the core action, key filters, and sort intent with no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with 100% schema coverage and safe annotations, the description is nearly sufficient. It could mention pagination via `next_url` or the related `app_store_versions__customer_reviews__list` sibling, but the schema and annotations fill most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 10 parameters. The description adds only a high-level summary of filtering by rating/territory and sorting by newest, which is helpful but does not materially expand on the schema's detailed field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List customer reviews for an app.' It also names the endpoint, which clarifies the operation. It does not explicitly differentiate from the similar sibling `app_store_versions__customer_reviews__list`, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives filter and sort guidance but no explicit when-to-use guidance or alternative exclusions. Given the existence of `app_store_versions__customer_reviews__list` and `customer_reviews__get`, the agent gets no help choosing among related review-listing tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with the readOnly and idempotent annotations, but adds no behavioral context beyond them: no note on response shape, absence behavior, or auth requirements. It simply restates the read operation with an endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence followed by a compact endpoint reference. Every element earns its place, and the main verb and resource are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, safely annotated read operation, the description plus schema is enough to select and invoke correctly. The only minor gap is not stating what the response contains or explicitly routing away from end_user_license_agreements__get, which is mitigated by the app-scoped wording.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the id parameter already documents accepted formats (app name, bundle ID, or numeric Apple ID), so the description need not add parameter detail. Baseline 3 is appropriate because the schema carries the 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?
States a specific verb ('Read'), a specific resource ('end user license agreement for an app'), and the exact endpoint. This separates it from sibling tools like end_user_license_agreements__get by making the app-scoped relationship explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this over sibling tools such as end_user_license_agreements__get or when not to use it. The implied context is reading an app's EULA, but there are no explicit alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description is fully consistent with them — no contradiction. The description adds light context about the response contents (bundle ID, SKU, primary locale) and the endpoint path. The schema's include parameter note about relationship call costs is useful behavioral context, but it lives outside the description itself, so the added value is modest.
Agents need to know what a tool does to the world before 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: the action is front-loaded ('Read one app by ID'), followed by the specific returned attributes and a compact endpoint suffix. There is zero filler — every word carries meaning and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-resource GET, the combination of strong annotations, a fully-described schema, and a pointed description leaves little ambiguity about how to invoke it correctly: identifier formats, optional include relationships, and field selection are all covered. Missing explicit error/auth expectations are minor because annotations already flag the safety profile and these are tool-family-wide concerns rather than tool-specific gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter well-documented: id lists all three accepted identifier forms, include explains comma-separated relationships and the per-row call cost, and fields_apps flags the >200KB row size trade-off. The description adds only a marginal hint that the default response includes bundle ID, SKU, and primaryLocale, so the baseline 3 holds without the description needing to compensate.
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?
States a specific verb and resource ('Read one app by ID') plus the salient returned attributes (bundle ID, SKU, primary locale). This differentiates it from the many sibling relationship getters (apps__ci_product__get, apps__game_center_detail__get) and the plural apps__list by making plain it returns one core app record. However, it doesn't explicitly name a sibling alternative, so it falls short of a full 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to select this tool over the dozens of sibling 'apps__*__get' relationship getters or apps__list for searching. The only usage hints live inside the parameter descriptions (e.g., include's 'costs one extra call per row'), which help invoke the tool but not choose it. An agent must infer tool selection from the name and description 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns by saying 'Read' and using a GET endpoint. It does not add meaningful behavioral context beyond that, such as error cases or response shape, but the annotation coverage lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by the explicit endpoint, with no filler or repetition. The key action and resource are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter GET operation, the description and schema provide enough for an agent to invoke it correctly. It could optionally clarify what 'marketplace search detail' contains or how this read relates to sibling create/update/delete operations, but that is not essential for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'id' parameter with valid formats (app name, bundle ID, or numeric Apple ID), so the description does not need to compensate. The description contributes no additional parameter detail, keeping this at the baseline for 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and a clear resource ('marketplace search detail for an app'), and the endpoint makes the operation unambiguous. It does not explicitly contrast with sibling marketplace_search_details create/update/delete tools, though the read verb implies the 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 is provided about when to use this tool versus alternatives such as marketplace_search_details__create, __update, or __delete. The read-only framing is implicit, but there are no explicit conditions, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, which already inform the agent of the write, idempotent, and non-destructive nature. The description adds the PATCH endpoint but doesn't clarify whether fields are partially updated or fully replaced, or any other behavioral effects 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 a single, focused sentence with the endpoint path, wasting no words. It front-loads the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a mutation with a nested request body and no output schema, yet the description does not explain the update semantics (e.g., partial vs. full) or what a successful response returns. It lacks any workflow context such as needing an existing review detail ID and relationship to the create/get tools. This is inadequate for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides descriptions for both parameters (id and body), so the baseline is 3. The description adds no additional parameter semantics; it simply restates the update action. The nested attributes are documented by types, but not explained 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 (Update) and the resource (App Store review detail), and includes the HTTP method/path for additional clarity. This distinguishes it from the create and get sibling tools, as the update verb is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the create or get variants, nor does it mention any prerequisites or workflow context. The only usage hint ('ID from the matching list call') is buried in the schema, not the description.
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, so the safety profile is clear. The description does not add any additional behavioral traits (e.g., pagination behavior, error handling, or response format). With strong annotations, a score of 3 is appropriate—the description is adequate but adds no value 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the action, followed by the endpoint in brackets. It contains no filler, is easy to read, and every element serves a purpose. This is an ideal length for a list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 8 parameters, no output schema, and moderate complexity (filtering, includes, pagination). The description fails to provide an overview of the response structure, pagination behavior, or how to effectively use the include and filter parameters. While the schema covers details, the description should offer a high-level summary of what the agent can expect, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters clearly (e.g., id is 'ID from the matching list call', include lists relationships). The description adds no additional parameter-level context or semantics beyond what is already in the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List the app preview sets') and the resource ('belonging to an App Store version localization'). It also includes the exact HTTP method and endpoint, leaving no ambiguity about what the tool does. While it does not explicitly differentiate from sibling tools like the screenshot sets list, the verb+resource combination is sufficiently specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., the very similar sibling for screenshot sets). There is no mention of prerequisites (e.g., needing a valid localization ID) or when not to use it. The description is purely declarative, leaving the agent to infer usage context from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is destructive. The description adds no extra context beyond the endpoint; it does not mention irreversibility, cascading effects, or consequences 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus endpoint, with no unnecessary words. It is perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter, no output schema, and strong annotations covering destructive/idempotent hints, the description is largely complete. It could mention any state restrictions (e.g., versions only deletable in certain states), but this is not essential for basic functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id parameter described as 'ID from the matching list call.' This is clear and sufficient; the description adds no additional 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 'Delete an App Store version' with a specific verb and resource, and includes the API endpoint. This unambiguously distinguishes it from sibling tools like create, update, and get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, nor any exclusions or prerequisites. The context is only implied by the tool name and description.
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 description simply restates the delete action, adding no extra context beyond the annotations. It doesn't disclose irreversible effects, permissions, or side effects, relying entirely on the destructiveHint annotation without elaboration.
Agents need to know what a tool does to the world before 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 focused sentence with the endpoint, no redundant text, and front-loads the action verb. It earns its place without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete with one parameter and annotations indicating destructive/idempotent behavior, the description is adequate. It includes the endpoint for reference, though it could mention reversibility explicitly, but the annotations cover the core safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'id' parameter described as 'ID from the matching list call.' The description adds no parameter-level detail, but the schema already fully documents the single parameter, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete a beta App Clip invocation localization') with a specific resource and includes the exact HTTP endpoint, distinguishing it from sibling create/update tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 or any prerequisites. The only usage hint (matching list call ID) appears in the schema, not in the description, and there's no mention of irreversibility or when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false. The description only restates 'Delete' and adds no additional context about irreversibility, permissions, or side effects, providing zero 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with the endpoint and no filler. Every word earns its place; highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and annotations declaring destructiveness, the description plus schema is mostly complete. However, it could mention that deletion is permanent or explicitly state the ID must be obtained from a prior list call (though schema covers that), so not a perfect 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 for the single id parameter with description 'ID from matching list call'. The description itself doesn't expand on parameters, but the schema fully documents it, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Delete' and resource 'beta app localization', clearly distinguishing it from sibling CRUD tools like beta_app_localizations__create/get/update. It also includes the API endpoint for additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives, no prerequisites or exclusions. The schema hint about ID from the matching list call is the only contextual clue, but the description itself provides no usage direction.
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=false, idempotentHint=true, destructiveHint=false. The description adds only the HTTP method (PATCH) and endpoint, which weakly implies partial update semantics, but it does not disclose side effects, required permissions, or behavior on omitted fields. No contradictory statements.
Agents need to know what a tool does to the world before 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 clean sentence plus endpoint, with no filler words. Every element contributes to identifying the tool's purpose and HTTP binding.
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 a straightforward update operation with rich annotations (idempotent, non-destructive) and a fully documented schema, the minimal description is adequate. It lacks any statement about the response shape or side effects, but for this simple tool, the provided structure is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters: id ('ID from the matching list call') and body ('JSON:API request body (Apple schema)'). The tool description itself adds no parameter meaning, but schema coverage is 100%, so the 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?
The description uses the specific verb 'Update' and names the resource 'beta app localization', clearly distinguishing it from sibling tools like create/delete/get/list. The appended endpoint '[PATCH /v1/betaAppLocalizations/{id}]' reinforces the precise action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., create for new localizations, get for reading). It does not mention prerequisites like needing an ID from a list call, nor does it exclude any scenarios. The only implicit signal is the verb 'Update'.
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/write behavior (readOnlyHint=false, destructiveHint=true), so the description need not repeat that. It adds the endpoint and 'RELEASE-level' qualifier, providing some context but not deep behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, including the endpoint for reference. It is appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too brief for a create operation with nested relationships and no output schema. It does not mention what the response contains, any preconditions, or clarify the meaning of 'RELEASE-level'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents the parameters. The description adds no extra meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('beta app review submission'), and includes the REST endpoint. This is specific enough to distinguish it from sibling list/get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The phrase 'RELEASE-level write' is ambiguous and does not explain prerequisites, context, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already declare (destructiveHint=true, idempotentHint=true). It does not mention that deletion is permanent or any other side effects. Since annotations cover the destructive nature, the description itself contributes no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with the endpoint, making it concise and front-loaded. There is no wasted or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one fully described parameter and annotations indicating destructiveness and idempotency, the description is mostly complete. It lacks an explicit mention of return value or side effects, but the low complexity and annotation coverage make it adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a full description of the only parameter ('ID from the matching list call'), covering 100% of parameters. The tool description adds no additional parameter context, so the baseline score 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?
The description uses the specific verb 'Delete' with the resource 'beta build localization', clearly identifying the operation. It also includes the REST endpoint, and the name distinguishes it from sibling tools like beta_build_localizations__create/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?
The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites, conditions, or consequences, aside from the schema's note about the ID coming from a matching list call, which is in the schema, not the description.
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 description only repeats the delete operation already indicated by the destructiveHint annotation and adds no new behavioral context such as permanence, effect on related data, or authentication requirements. It does not contradict annotations but fails to go beyond them.
Agents need to know what a tool does to the world before 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, front-loaded sentence including the endpoint path. Every part is informative with no filler, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with a fully described parameter and annotations covering safety, the description is largely sufficient. It lacks explicit usage guidance but is complete for the core action and resource.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%: the single 'id' parameter includes the useful note 'ID from the matching list call.' The tool description itself adds no further parameter meaning, aligning with 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 a specific action ('Delete') and a specific resource ('beta feedback crash submission'), making it unambiguous and distinguishable from related tools like beta_feedback_screenshot_submissions__delete. The REST endpoint is also included for 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 alternatives, nor does it mention prerequisites or exclusion criteria. The only contextual hint comes from the schema's parameter description, not the tool description.
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, and destructiveHint=false, fully covering the safety profile. The description adds the endpoint path [GET /v1/betaLicenseAgreements/{id}/app] as helpful context but does not disclose additional behaviors such as response format 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 extremely concise: one sentence plus the endpoint path. Every word adds value, and the core action and resource are immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one parameter, no output schema), the description is mostly complete for a read operation. However, since there is no output schema, a note about the response containing the app resource would have been helpful for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter 'id' with description 'ID from the matching list call.' Schema description coverage is 100%, so the schema already provides necessary context. The description adds no additional parameter meaning 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 'Read the app for a beta license agreement' clearly identifies the action (read) and resource (app) scoped to a beta license agreement, and the endpoint path confirms the relationship. It distinguishes from the sibling 'apps__beta_license_agreement__get' which does the inverse, though this is not explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The sibling 'apps__beta_license_agreement__get' performs the inverse operation, but the description does not mention this or any other selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description says only 'Link builds to a beta tester' and includes the endpoint. It does not clarify whether the operation appends to existing relationships or replaces them, nor does it mention any side effects or prerequisites. Annotations already communicate write/non-idempotent/non-destructive status, and the description adds no complementary 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?
The description is one concise sentence followed by the API endpoint, with no redundant information. It is front-loaded and every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple relationship-add operation. Combined with comprehensive schema descriptions and annotations, the one-sentence description is nearly sufficient. A minor missing detail is an explicit statement that 'id' refers to the beta tester's identifier, but this is inferable from the endpoint and tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'id' ('ID from the matching list call') and 'body' (JSON:API request body), including the nested data array and type enum. The description mentions no parameters, but the schema fully documents them, so the 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?
The description uses a specific verb ('Link'), direct object ('builds'), and target ('to a beta tester'), which clearly identifies the action. It distinguishes from sibling tools like beta_testers__builds__remove and beta_groups__builds__add, and the endpoint reinforces the direction.
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 builds__individual_testers__add (the inverse relationship) or beta_testers__builds__remove. It merely restates the action without giving context or exclusions, so the agent must infer usage from the name alone.
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 description's 'Read' adds little. It only appends the endpoint path but discloses no additional behaviors (e.g., what data is returned, relationship inclusion effects, or error conditions). This goes not beyond the safety profile already covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus an endpoint reference, with no unnecessary words or repetition. It is concise and front-loaded with the action and resource.
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 with one required parameter and strong annotations, the description is mostly sufficient. The resource name and endpoint clearly indicate what is being fetched, and the schema covers parameters. However, without an output schema, it does not explicitly state what fields the beta detail contains or any error scenarios, leaving a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema provides thorough explanations for both parameters, including the relationship inclusion trade-off in 'include'. The description itself adds no parameter context, but the schema fully carries the semantic load, so the 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?
The description uses the specific verb 'Read' and identifies the resource as 'the build beta detail for a build,' which clearly differentiates it from sibling tools like builds__get or build_beta_details__get. The endpoint path in brackets reinforces the resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as build_beta_details__get or builds__get. The only hint is the schema note for 'id' about getting it from a list call, but the description itself lacks any usage context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive/write behavior and non-idempotency. The description adds the endpoint and 'RELEASE-level write' as extra context, but does not disclose additional behavioral details like required app relationship, follow-up steps, or side effects 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It front-loads the core purpose and adds the useful endpoint reference, making it optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex create operation with a nested JSON:API body and no output schema, yet the description does not explain the overall build upload process, prerequisites, or what happens after creation. The rich schema covers parameter structure but not the operational context needed to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 body structure is fully documented in the schema. The description adds no parameter-level meaning beyond what the schema already provides, warranting the baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create') and the resource ('build upload'), and includes the exact endpoint. It is unambiguous and distinguishes this creation tool from related siblings like build_uploads__get, build_uploads__delete, and apps__build_uploads__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 is provided on when to use this tool versus alternatives such as build_upload_files__create or build_uploads__delete. The 'RELEASE-level write' hint gives some context but does not explain the build upload workflow or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=true), so the agent knows it's a destructive operation. However, the description itself adds no behavioral context beyond the endpoint path—it doesn't clarify permanence, cascading effects, or error behavior, which would add value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence stating the action and endpoint, with no wasted words. It is appropriately sized for a simple delete operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one well-documented parameter and clear annotations, the description is nearly complete. It includes the HTTP method and endpoint, and the schema/annotations cover the rest. A minor gap is the lack of any statement about return values or side effects, but given the tool's simplicity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'id' parameter documented as 'ID from the matching list call.' The tool description adds no additional parameter semantics, so the 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?
The description explicitly states the action ('Delete') and the resource ('marketplace search detail'), and includes the REST endpoint for precision. This clearly distinguishes it from sibling tools like marketplace_search_details__create and marketplace_search_details__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 guidance is provided on when to use this tool versus alternatives. The description only states the action, without mentioning when deletion is appropriate, what prerequisites exist (e.g., the resource must exist), or why one would choose delete over update or create.
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 disclose readOnlyHint=false, idempotentHint=true, and destructiveHint=true. Description adds 'RELEASE-level write' and the HTTP method, but does not explain destructive implications (e.g., setting removed=true might remove the item). 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?
Very concise: a single sentence plus HTTP path, with no redundant text. The verb 'Update' is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a nested-body mutation tool with destructiveHint=true and no output schema, but the description only says 'Update a review submission item.' It lacks context about effects (removed/resolved), return values, or any constraints, leaving significant gaps for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents id and body. The description adds no extra meaning beyond what the schema already provides, leaving semantics at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States 'Update a review submission item' with the HTTP path, clearly identifying the action and resource. Distinguishes from sibling create/delete tools for the same resource.
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 vs alternatives like review_submissions__update or review_submission_items__create. Does not mention what attributes can be changed or prerequisites, so the agent must infer usage from the schema.
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 description adds no behavioral context beyond what the annotations already convey. Annotations indicate idempotent and non-destructive, but the description does not clarify partial update semantics, return values, or any side effects. It merely restates the update action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and resource, and includes the endpoint. There is no wasted wording or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, when combined with the detailed JSON:API schema and annotations, is adequate for basic usage. However, it lacks information about the update behavior (e.g., whether omitted attributes are preserved or cleared), potential error conditions, and expected response. These are not covered by annotations or an output schema, so the description is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both parameters (id, body) have descriptions. The id description ('ID from matching list call') is helpful, but the body description only references an Apple schema name, which is obscure. The tool description adds no extra parameter meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update), the resource (android to iOS app mapping detail), and the HTTP method with endpoint. It distinguishes from sibling CRUD tools like create, delete, and get by explicitly using 'update'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: it is for updating an existing mapping detail, as opposed to creating or deleting. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention prerequisites or context like needing the ID from a list call (though the schema notes this).
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=false, idempotentHint=true, and destructiveHint=false. The description adds only the endpoint and the generic update verb, which is already implied by the tool name. It does not disclose any additional behavioral traits such as authentication requirements or effects on related resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of one concise sentence plus the endpoint. It front-loads the core purpose with no wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal but adequate for a simple update operation. The input schema provides detailed nested structure for attributes and relationships, and there is no output schema. However, the description does not summarize the updateable fields or any required relationship updates, which would be helpful for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for 'id' (ID from the matching list call) and 'body' (JSON:API request body referencing Apple schema). The description provides no additional parameter context beyond the schema, which is sufficiently detailed with nested attributes and relationships. 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 'Update an App Clip default experience' with the specific PATCH endpoint. This unambiguously identifies the resource and action, distinguishing it from create, delete, and get siblings for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying an existing App Clip default experience but does not explicitly state when to use it over create or delete, nor does it mention prerequisites like having an existing ID from a list call. No alternatives are referenced.
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 idempotentHint=true, so the description's safety burden is light and it does not contradict them. It adds the endpoint path and confirms the operation is a scoped read of events for a single app. No additional behavioral traits (pagination defaults, auth requirements) are disclosed, which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The entire description is two short sentences with no filler—the verb/resource statement is front-loaded, and the REST endpoint is a compact second sentence. Nothing could be trimmed without losing 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 read-only list endpoint with annotations covering safety and a schema documenting every parameter, the minimal description is nearly adequate. However, there is no output schema and the description does not characterize the return shape or pagination behavior beyond the schema's 'limit' hint, leaving modest gaps for an agent to resolve.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—all seven parameters have individual descriptions, including helpful details like 'A full row set can exceed 200 KB' and the relationship-cost note on include. The tool description itself adds no parameter-level detail, but per the rubric, high schema coverage sets the baseline at 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a distinct resource ('app events'), and the scoping relationship ('belonging to an app'), and appends the exact REST endpoint [GET /v1/apps/{id}/appEvents]. No sibling tool targets app events, so the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to choose this tool over alternatives, and no alternatives or exclusions are named. Context signals show a large sibling suite (~250 tools), so an agent must infer usage mostly from the name. The schema's include-parameter note ('one extra call per row returned') is the only usage hint, and it lives at parameter level rather than tool level.
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, providing safety and idempotency information. The description adds the endpoint hint [GET /v1/apps] and the app ID usage context, but does not disclose behavioral traits like pagination handling or rate limits. Given annotation coverage, the description provides minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences plus the endpoint in brackets. Every word serves a purpose: the first sentence states the action, the second provides actionable guidance. No fluff, 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 tool's complexity (16 parameters, no output schema) and the thoroughness of the schema descriptions, the description is adequate but not complete. It lacks explanation of pagination, filtering capabilities, or how to use the include parameter for related data. The schema covers many details, but the description could provide a higher-level usage pattern. It is minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 16 parameters have descriptions in the input schema, giving 100% coverage. The description does not add any additional parameter meaning beyond what the schema provides. With high schema coverage, the baseline is 3, and the description does not exceed it.
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 all apps in the App Store Connect account and directs the agent to start here when needing an app ID. The verb 'List' and resource 'apps' are specific. However, it does not explicitly differentiate from sibling tools like apps__get, though the guidance to start here implies it's the primary listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises 'Start here when you need an app ID,' which gives a clear starting point for finding an app identifier. However, it does not specify when not to use this tool or mention alternatives such as apps__get for retrieving a single app once the ID is known. The usage context is implied but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false, clearly indicating this is a safe, read-only operation. The description adds the endpoint path but no additional behavioral details (e.g., pagination behavior, rate limits, or what happens if the id doesn't exist). A 3 is appropriate as annotations do the heavy lifting here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with a single sentence and endpoint path. Every word adds value, no filler or repetition. The endpoint path is provided in brackets for immediate reference, which is efficient 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?
Given that this is a simple listing tool with excellent annotations (readOnlyHint, idempotentHint) and 100% schema coverage, the description is adequate but not enriched. It doesn't explain the relationship to experiment treatment localizations or provide examples. No output schema exists, but for a listing endpoint, the description is minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all 8 parameters are described in the schema. The description itself does not add any parameter-level details beyond what the schema already provides. Baseline 3 is correct since the schema is comprehensive and no additional value is needed from the description.
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 this tool lists app preview sets belonging to a specific App Store version experiment treatment localization. It includes the exact API endpoint path, making the scope unambiguous. However, it does not differentiate from the sibling tool `app_store_version_localizations__app_preview_sets__list` which has a similar purpose but for a different parent resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides the endpoint path but no explicit guidance on when to use this tool versus alternatives like the sibling tool that lists preview sets for a version localization. The context of being for experiment treatment localizations is implied but not contrasted with other related lists.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds no extra behavioral context such as side-effects, permissions, rate limits, or irreversibility. It merely restates what the annotation already conveys, offering no added value beyond the endpoint.
Agents need to know what a tool does to the world before 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 action sentence plus the endpoint. It is front-loaded, contains no filler, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one required parameter, no output schema) and annotations cover the destructive nature. However, the description does not mention what happens to associated resources (e.g., screenshots, previews) or what response to expect, leaving some ambiguity for an agent unfamiliar with the API.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'id' parameter with 'ID from the matching list call.' The description adds no parameter-specific information, but with 100% schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the specific resource ('App Store version localization'), and includes the REST endpoint for precision. This distinguishes it from sibling tools that create, update, or get the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when deleting a specific localization. However, it provides no explicit guidance on when to use it versus alternatives (e.g., update or create), nor does it mention any prerequisites or consequences. The schema's 'ID from the matching list call' is the only hint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the endpoint and 'Read', but does not disclose additional behavioral traits such as response format, pagination, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus the endpoint, front-loaded with the verb and resource. No wasted words; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a simple read tool with one parameter and strong annotations, the description is minimally sufficient. However, it lacks information about what the response contains or any caveats (e.g., that the phased release may not exist), which would be helpful given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters (one 'id' with description 'ID from the matching list call.'). The description does not add any additional meaning beyond the schema, so it does not compensate or enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' with the resource 'App Store version phased release for an App Store version', clearly indicating this is the read operation. It distinguishes itself from sibling tools that create, delete, or update phased releases, and includes the exact API endpoint for precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for fetching an existing phased release, nor does it point to related tools for creating/updating. The agent must infer usage from the name and endpoint.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which convey the safety profile. The description adds the specific endpoint scoping (the build associated with a version) and the HTTP method. However, it doesn't note that the response includes typical App Store Connect API fields, pagination, or that the 'id' must come from a list call. With annotations covering the core behavioral traits, a 3 is appropriate—it adds context about the resource relationship but not additional behavioral caveats.
Agents need to know what a tool does to the world before 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 plus an endpoint reference. It is optimally concise, front-loading the main action ('Read the build for an App Store version.') and including the exact HTTP path for developers. 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?
Given the tool has one parameter, a simple read operation, and high schema coverage, the description is nearly sufficient. However, for agents navigating the large sibling list, it would benefit from noting that this is the counterpart to app_store_versions__build__set, and that the id is an appStoreVersion id (the schema already says this). The output schema is absent, but for a simple read, the description is reasonably complete. It still leaves a small gap regarding the expected output shape, but for a GET tool, that may be implicitly understood.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: the only parameter 'id' has a description 'ID from the matching list call.' The description's path /v1/appStoreVersions/{id}/build adds meaning by indicating the id belongs to the appStoreVersion. The parameter description in the schema already says it comes from a list call. The tool description doesn't need to repeat the parameter details; the schema handles it well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'Read' and the resource 'the build for an App Store version'. It clearly indicates this is a GET operation to fetch a build associated with a specific App Store version. It is distinguishable from siblings like app_store_versions__build__set (which writes) and builds__app_store_version__get (which fetches the app store version for a build), though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes the HTTP method and path pattern, implying it is for retrieving a build linked to an App Store version. It does not explicitly state when to use this over alternatives, but the verb 'Read' and the path indicate its read-only nature. Given the sibling list includes many related tools, the description could be clearer about when to choose this vs. builds__app_store_version__get, but the endpoint structure gives reasonable context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=true. The description adds 'RELEASE-level write' as a permission context and names two specific updatable fields, but it does not clarify whether the update is partial (PATCH semantics) or what happens to omitted fields, nor any side effects beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence, an endpoint reference, and a permission tag. Every word is informative and the action is front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex body schema and the absence of an output schema, the description is minimal but not wholly inadequate. It conveys the core purpose and permission level, but lacks guidance on how to construct the body for partial updates, which other fields are updatable, and what the response contains. The detailed schema partially compensates, but semantic gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the top-level parameters, with id and body having descriptions. The description adds value by highlighting releaseType and earliestReleaseDate as the attributes to update, but the complex nested body structure and other attributes lack semantic explanation in both the schema and the description, so the added meaning is limited.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Update an App Store version' and specifies two key attributes (release type and earliest release date), which distinguishes it from create/get/delete tools. However, it does not explicitly contrast with similar update tools like app_store_versions__build__set, so it lacks full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing App Store version via the PATCH endpoint, and the id parameter description mentions 'ID from the matching list call.' However, there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites beyond the id.
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=false, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-read-only, idempotent mutation. However, the description adds no extra behavioral context beyond what the annotations and the word 'Update' convey. It does not mention any side effects, permission requirements, or the fact that only visibleInAppStore is updatable, which would be valuable beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one short sentence plus the endpoint reference. It contains no fluff or redundant information. Every word earns its place, making it easy to parse and act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation with two well-documented parameters and no output schema, the description plus schema provides sufficient information to understand what the tool does and what inputs are needed. However, it lacks any guidance on expected response format, partial vs. full replacement semantics, or when this update should be used relative to other update tools. The annotation set fills some safety context, but the description is minimal for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'id' ('ID from the matching list call') and 'body' ('JSON:API request body (Apple schema: AppTagUpdateRequest)') have meaningful descriptions. The tool description itself adds no parameter-level insight beyond the schema, so it rests at the baseline of 3. The nested 'data' object's properties are self-explanatory via their types and enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an app tag' clearly states the verb (update) and resource (app tag), and the endpoint [PATCH /v1/appTags/{id}] reinforces the action. It is distinct from sibling tools like app_tags__territories__list or apps__app_tags__list, which are read-only list operations, and from other update tools that target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage context: it is an update operation and the endpoint indicates it modifies an existing app tag. The id parameter description in the schema ('ID from the matching list call') gives a hint about prerequisites, but the tool description itself does not explicitly state when to use this tool versus alternatives or any exclusions. The usage is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not restate these. The description does not contradict annotations. However, it does not add extra behavioral context such as rate limits, response size warnings (though the schema field note mentions 200 KB), or pagination behavior beyond the parameter descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence plus the endpoint hint). It is front-loaded with the core purpose. No wasted words. However, it could have added a tiny bit more usage guidance without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 6 parameters (all optional) and no output schema, the description is adequate but minimal. It does not explain the return format (e.g., list of localization objects with metadata like pagination links). The endpoint hint is helpful, but for a list tool with no output schema, more description about what is returned would be useful.
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% (all 6 parameters have descriptions). The descriptions are detailed, providing practical guidance (e.g., 'Use numeric Apple ID from apps__list, not the bundle ID', 'A full row set can exceed 200 KB'). The description adds the endpoint context, but the schema already carries the parameter semantics well.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List beta app localizations' which is a clear verb+resource combination. It distinguishes itself from sibling tools like 'beta_app_localizations__create', 'beta_app_localizations__delete', and 'beta_app_localizations__update' by the 'List' action, and from 'apps__beta_app_localizations__list' which scopes to a specific app's localizations. The HTTP GET endpoint is also provided for additional clarity.
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 is minimal and does not explicitly state when to use this tool vs alternatives. It does not mention filtering prerequisites or pagination strategy. While the parameter descriptions in the schema offer some guidance (e.g., 'Use numeric Apple ID, not bundle ID' for filter_app), the description itself lacks usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description does not add behavioral context beyond stating it lists resources. With annotations present, a score of 3 is appropriate as the description is not harmful but adds no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise—one line with the verb, resource, and the direct API endpoint. Every element is useful and there is no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks details about required filters (filter_build is required per schema), pagination behavior, and what a beta app review submission represents. Given no output schema, additional context about return structure would help. Still, for a list tool with well-documented schema, it is minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with well-described parameters. The description adds no parameter-level information beyond what the schema already provides. Baseline 3 is correct per the scoring 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 uses the specific verb 'List' and resource 'beta app review submissions', clearly distinguishing it from sibling tools like beta_app_review_submissions__create (create) and beta_app_review_submissions__get (single resource). The API endpoint is also provided for direct reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus siblings such as review_submissions__list (App Store review) or the get variant. There are no contextual cues about prerequisites or appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, idempotent, non-destructive operation. The description adds the HTTP method PATCH and endpoint, which provides some behavioral context (partial update), but does not disclose permissions, side effects, or reversibility. This is a modest addition 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 a single sentence plus the endpoint, front-loaded with the action. There is no wasted text or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations cover request structure and safety profile, but the description lacks response information (no output schema) and any usage guidance. It is adequate for a simple update but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including the id purpose ('ID from the matching list call') and the JSON:API body structure. The description itself adds no parameter information, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the target resource ('a beta license agreement'), and includes the specific endpoint. This distinguishes it from sibling tools like get, list, or app get for the same resource.
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. It does not mention prerequisites, required prior calls (e.g., fetching the ID), or scenarios where this tool is appropriate versus other beta license agreement tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and idempotentHint=true, and the description adds the PATCH method, which is consistent. However, it does not disclose whether the update is partial or full, what happens to omitted fields, or any side effects beyond the annotation baseline.
Agents need to know what a tool does to the world before 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 plus the endpoint, with no superfluous words. It is front-loaded and concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with a well-defined schema, the description is adequate but does not explain return values, error conditions, or update semantics beyond the schema. Given the complexity of nested objects, slightly more context about what attributes can be updated would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the two parameters, with meaningful descriptions for 'id' and 'body'. The top-level description adds no parameter information beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a beta recruitment criteria' clearly states the action (update) and resource (beta recruitment criteria), and the PATCH endpoint reinforces the HTTP method. It differentiates from sibling tools like create/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 guidance is provided on when to use this tool versus alternatives, no prerequisites, and no mention of related tools like beta_recruitment_criteria__create or beta_groups__beta_recruitment_criteria__get. The usage is implied only by the tool name.
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=true and idempotentHint=true. The description merely restates 'List' and gives the HTTP endpoint, adding no behavioral context beyond what annotations and the tool name already convey. It does not mention pagination, response size caveats, or filtering nuances.
Agents need to know what a tool does to the world before 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 states the action and includes the endpoint. It is extremely concise, front-loaded, and contains zero 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 read-only list tool with well-documented parameters and safety annotations, the description is minimally adequate. However, with no output schema, it does not describe what the returned options look like or how they are used, leaving some ambiguity for an agent unfamiliar with beta recruitment.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with meaningful descriptions for limit, next_url, and fields. The description adds no additional parameter meaning, so the baseline 3 applies because the schema carries the semantics 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 uses a specific verb ('List') and resource ('beta recruitment criterion options'), and includes the exact endpoint path. This clearly distinguishes it from sibling tools like beta_recruitment_criteria__create or beta_groups__beta_recruitment_criteria__get.
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 clearly implies this is for listing beta recruitment criterion options, but it does not explicitly state when to use it versus alternatives or provide exclusions. For a simple list resource, the context is understandable but not fully spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description's 'Unlink' plus DELETE method aligns with these. However, the description adds no further behavioral context (e.g., that the beta tester itself is not deleted, or that the relationship removal may affect app access). It provides the endpoint, but that is not additional behavioral transparency 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 a single, concise sentence that front-loads the action. The endpoint specification is also succinct and informative. Every word earns its place, with zero wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a nested body parameter and is a destructive operation, the description is somewhat minimal but not inadequate. The schema fills in parameter details, and annotations cover the safety profile. It lacks a note about the scope of the removal (e.g., only the relationship is deleted), but for a straightforward relationship-removal tool, this is sufficient to function correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing descriptions for both id and body. The tool description adds no parameter semantics beyond what the schema already states. Baseline of 3 is appropriate since the schema carries the parameter explanation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Unlink apps from a beta tester', which is a specific verb (unlink) with a resource pair (apps, beta tester). It also includes the exact DELETE endpoint, further disambiguating it from sibling tools like apps__beta_testers__remove or beta_testers__beta_groups__remove.
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. Sibling tools such as builds__individual_testers__remove or beta_groups__beta_testers__remove exist, but the description does not distinguish when each should be used. It only states the action without contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, readOnlyHint=false, and destructiveHint=false. The description adds the PATCH method and specific endpoint, implying a partial update, but does not disclose any additional behavioral context such as optional fields or error conditions. Minimal beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with zero waste. Including the HTTP endpoint inline provides helpful orientation without verbosity, making it appropriately sized and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a complex nested body and related workflow, but the description is sparse. It doesn't explain when to use this endpoint (e.g., marking a file as uploaded) or the implications of updating checksums. However, the rich schema and annotations provide enough details for a straightforward update operation, making it minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add extra semantics, but the schema already provides descriptions for id and body, including nested structure details, so the necessary meaning is present.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 'Update a build upload file' with a clear verb ('Update') and resource, and includes the HTTP endpoint path. This distinguishes it from sibling tools that create or get build upload files.
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, typical scenarios, or exclusions. The only subtle clue is the word 'update', which doesn't provide enough context to choose among similar build upload 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 a mutating, idempotent, non-destructive operation. The description adds the PATCH method, implying partial update, but does not disclose additional behavioral details such as side effects, required permissions, or failure modes. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the HTTP endpoint, front-loading the purpose with no unnecessary words. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the basic purpose but lacks guidance on usage context, return values, or error handling. However, with complete schema documentation and annotations, it meets the minimum viable threshold for a standard update tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'body' described in the input schema. The description itself does not add parameter-specific information beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('marketplace search detail'), and includes the HTTP method and path ('PATCH /v1/marketplaceSearchDetails/{id}'). This distinguishes it from the sibling create and delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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 creating or deleting a marketplace search detail, nor any prerequisites or context. It simply states the action without explaining when it is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description adds no behavioral traits beyond the read operation itself. It does not mention response size, authentication, or any limitations. No contradiction, but the description contributes no meaningful transparency beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two short sentences, starting with the action and including the endpoint. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID operation, the description, schema, and annotations are sufficient. The lack of an output schema is mitigated by the clear purpose and parameter documentation. A minor gap is no explicit mention of when to use this tool versus list operations, but overall context is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions provide complete coverage for both parameters, including the enum values and size warning for fields_analyticsReportInstances. The tool description itself does not add parameter explanation, so a baseline score of 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Read' with a clear resource ('analytics report instance') and scope ('by ID'), which distinguishes it from list operations and sibling tools like analytics_reports__instances__list. The HTTP endpoint further specifies the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied via 'by ID' and the schema's 'ID from the matching list call', but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions. No direct reference to sibling tools is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the endpoint path but no extra behavioral context such as pagination behavior or response format. It does not contradict annotations and meets the baseline given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with a useful endpoint reference. It is front-loaded and avoids unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward list operation with good annotations and complete schema coverage. However, it lacks guidance on how it relates to adjacent instance/segment tools, which would make it fully complete for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all five parameters described. The description does not add parameter-level meaning beyond the schema, so a baseline of 3 is appropriate. The filter descriptions are present in the schema, and the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('List') on a specific resource ('instances belonging to an analytics report'), making the tool's purpose unambiguous. The endpoint reference further clarifies scope. This distinguishes it from sibling tools like analytics_reports__get or analytics_report_instances__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 is provided on when to use this tool versus related tools such as analytics_report_instances__get or analytics_report_instances__segments__list. There is no mention of prerequisites, filtering options, or alternative paths.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and destructiveHint=false. The description simply says 'Read' and provides the HTTP method, adding no behavioral context beyond annotations. No mention of response format, error handling, or relationship-related behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that immediately conveys the primary action and target, followed by the endpoint. No filler or redundant words. It is appropriately sized for a simple getter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation with strong annotations and complete schema descriptions, the description is adequate. It makes the core operation clear, though it could mention that related data can be included via the include parameter. The lack of an output schema is mitigated by the simplicity of the resource.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all three parameters with descriptions, achieving 100% schema_description_coverage. The tool description itself adds no parameter details beyond mentioning the ID. Baseline of 3 applies because the schema carries the parameter documentation burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Read one app category by ID.' This distinguishes it from sibling list and related-resource endpoints. The REST endpoint [GET /v1/appCategories/{id}] reinforces the single-resource operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single category by ID, but does not explicitly mention when to use alternatives like list, parent, or subcategories. Context suggests the appropriate use case, but no exclusions or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no additional behavioral context such as response size, rate limits, or default field behavior, merely restating the read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence plus endpoint reference; extremely concise and front-loaded with no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read with complete schema and annotation coverage. The description lacks explanation of default return fields, but annotations and schema compensate sufficiently for this low-complexity operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (id with 'ID from the matching list call' and fields with a clear description), so the description need not add more. Schema coverage is 100%, placing this 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?
Description states 'Read one App Clip advanced experience image by ID' with a specific verb and resource, clearly distinguishing it from sibling create/update operations for the same resource. The endpoint is also included for technical clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implicitly clear (fetch a single image by ID), but no explicit when-to-use guidance or comparisons to alternatives (e.g., list or update tools) are provided in the description.
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, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no substantive behavioral context beyond affirming the read and the ID parameter; it neither contradicts annotations nor reveals additional traits like rate limits or response shapes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise, using one sentence and a method reference. It is front-loaded with the verb 'Read' and carries no filler. Every element serves a purpose, making it ideal for quick agent comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the annotations, and the highly descriptive schema, the short description is sufficient to enable correct invocation. The lack of an output schema is mitigated by the resource name and the parameter descriptions, which indicate response composition. A minor gap is the absence of explicit error/status expectations, but not critical for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with detailed explanations for the id, include, and fields parameters. The tool description itself adds no parameter-specific details, so the baseline of 3 applies since the schema effectively carries the semantic burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the resource ('one App Clip advanced experience by ID'), distinguishing it from related operations like create or update. The endpoint reference reinforces the specific singleton read behavior.
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. It does not mention that the ID comes from a list call, nor does it exclude cases like listing all experiences. The only implicit hint is the phrase 'by ID', which is insufficient for explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 'Read' aligns with those. However, the description adds no extra behavioral context such as error handling, availability, or relationship behavior beyond what annotations and schema already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource, followed by the endpoint path. It contains no filler or redundant information, earning top marks for structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID operation with rich schema annotations and full parameter descriptions, the description is functionally sufficient. However, it omits any mention of optional relationship inclusion or what the response contains, though the schema partially compensates. Still, given the annotations and schema, the description is nearly complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with each parameter (id, include, fields_...) having explicit descriptions. The tool description only mentions 'by ID,' but the schema already explains the ID source and optional parameters, so the description adds no additional semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Read' and the resource 'App Clip App Store review detail' with an ID input, clearly indicating this is a single-item get operation. It distinguishes itself from sibling create/update/delete tools and includes the HTTP endpoint for additional 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 choose this tool over alternatives, nor does it mention the prerequisite that the ID comes from a prior list call (though the schema does). It only states what the tool does, so an agent must infer usage from the name and schema.
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 destructiveHint=true and readOnlyHint=false, and the description merely restates the deletion action without adding extra behavioral context such as irreversibility, cascading effects, or permission requirements. No additional transparency beyond annotations is offered.
Agents need to know what a tool does to the world before 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 efficiently states the action and includes the REST endpoint. No wasted words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and well-covered annotations, the description is sufficiently complete. It lacks explicit mention of permanence or side effects, but the destructiveHint annotation covers the key risk, and the schema provides param details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the id parameter already includes 'ID from the matching list call,' so the tool description adds no new parameter meaning. Baseline for high schema coverage is 3, and the description doesn't compensate further.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an App Clip default experience' with a specific verb and resource, and the REST endpoint is included for clarity. This distinguishes it from sibling tools like get, update, and create for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for deletion, but lacks explicit guidance on when to use versus alternatives. The 'ID from the matching list call' hint provides a prerequisite, but there is no mention of exclusions or comparative context with get/update tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool destructive and idempotent, and the description adds no extra behavioral context beyond restating the delete action and showing the HTTP endpoint. No additional details about consequences, authorization, or rate limits are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It immediately states the action and resource, and includes the endpoint notation without unnecessary embellishment.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one well-documented parameter and strong annotations (destructive, idempotent), the description is mostly complete. It lacks only explicit information about return behavior, but that is common for delete operations and the annotations cover the safety profile.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'id' parameter already clearly described as 'ID from the matching list call.' The tool description adds no further parameter-level detail, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Delete') on a specific resource ('an App Clip header image'), clearly distinguishing it from sibling operations like create, get, and update. The HTTP endpoint is also provided for additional clarity.
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 its usage context (when you need to delete an App Clip header image) but does not explicitly discuss alternatives or exclusions. Since the tool name is self-explanatory, the guidance is somewhat implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only and idempotent, so the description does not need to restate that. However, it adds no additional behavioral context such as pagination behavior, permission requirements, or scope constraints beyond what the annotations and schema already provide. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by the endpoint, containing no redundant or extraneous information. It is front-loaded with the action and resource, making it efficient for an agent to process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with comprehensive schema and clear annotations, the description is sufficient to select and invoke the endpoint. It lacks explicit return-format or pagination details, but those are partially covered by the schema parameters (limit, next_url). Without an output schema, a bit more context could help, but the tool is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds slight clarity that the id parameter refers to the parent App Clip ID via 'belonging to an App Clip', which aids the cryptic schema description 'ID from the matching list call.' However, it does not elaborate on limit, include, next_url, or other parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'List the App Clip default experiences belonging to an App Clip.' This specifies the verb (List), the resource (App Clip default experiences), and the scope (belonging to an App Clip), distinguishing it from sibling tools like create/get/update/delete and other list endpoints. The inclusion of the HTTP endpoint reinforces the resource path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as app_clip_default_experiences__get for a single experience or app_clips__list for App Clips themselves. The description only states the operation and does not mention use cases, exclusions, or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the description does not need to restate those. However, it adds no extra behavioral context such as irreversibility, cascading effects, or authentication requirements. The description is consistent with annotations and provides the endpoint, but offers little additional value beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short clauses with no filler or redundancy. It front-loads the action and immediately provides the HTTP endpoint. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description plus annotations and schema provide enough context to invoke it correctly: we know it deletes a specific resource by id, that it is destructive and idempotent, and where the id comes from. No output schema is needed for a delete operation. The only minor gap is the lack of any usage context or alternatives, which prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents the single 'id' parameter with the helpful description 'ID from the matching list call,' giving 100% coverage. The tool description itself does not add further parameter detail, so the baseline score of 3 is appropriate. The endpoint path '/v1/appInfoLocalizations/{id}' does reinforce that id is a path parameter, but that is already implied by the schema and endpoint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('Delete') and a specific resource ('app info localization'), clearly distinguishing this tool from sibling create/get/update actions. The HTTP endpoint in brackets reinforces the exact operation. This is unambiguous and properly scoped.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this tool versus alternatives like app_info_localizations__update or app_info_localizations__get. It does not mention prerequisites, consequences, or that the ID should come from a prior list call. The only usage hint is buried in the schema, not the description.
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, and destructiveHint=false, so the safety profile is covered. The description's 'Read' and GET endpoint are consistent and add mild context, but they don't reveal behavior beyond the annotations, such as auth requirements, pagination, or relationship-fetching caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, plus a compact endpoint reference. No filler or redundant wording. Every phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity read tool, the description plus schema and annotations is nearly sufficient: id and include are documented, the endpoint is explicit, and the read-only behavior is annotated. No output schema exists, but the resource name and endpoint make the return focus reasonably clear. The only real gap is alternative-usage guidance, which is already captured in the usage_guidelines dimension.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents both parameters: id and include. The endpoint string hints that id goes in the path, but the description adds no semantic detail beyond what the schema already provides. Baseline 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Read'), a specific resource ('app price schedule'), and the target ('for an app'). The appended endpoint further disambiguates the exact operation. The resource name is unique enough among siblings to distinguish it from pricing tools like pricing__get_subscription_price.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus related pricing or schedule tools. The description only says 'for an app,' which does not help an agent choose among the many sibling tools. No exclusions or alternative routing 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, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds the GET endpoint, reinforcing read-only behavior, but does not disclose pagination, response shape, or auth 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?
One tight sentence plus the endpoint path, with no filler or redundant restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list endpoint, the schema fully documents the 10 parameters and the description gives the resource and scope. The absence of an output schema is manageable for a standard list call, though a note on the return shape or pagination would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 10 parameters have schema descriptions, so the description does not need to repeat them. It adds no extra semantics about id, sort, filters, include, or pagination beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description names a specific action ('List'), a concrete resource ('background assets'), and a clear scope ('belonging to an app'), so an agent can tell what the endpoint returns. It does not explicitly differentiate from siblings, but the resource is distinct from the many other apps__* list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is implied by the verb and resource: use it when background assets for an app are needed. It provides no explicit when-not-to-use guidance or alternative endpoints, though there is no obvious same-resource sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read' verb is consistent with those annotations. The description adds the endpoint path but no additional behavioral context such as return shape or side effects, which is acceptable given the safe read-only profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences contain exactly the needed information: what the tool reads and the exact endpoint. No filler, repetition, or unnecessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only, idempotent tool with no output schema, the description plus schema is largely sufficient for correct invocation. The main missing piece is explicit routing among the closely related beta app review detail siblings, but the app-scoped endpoint makes accidental misuse unlikely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter is fully documented in the schema, including accepted forms: app name, bundle ID, or numeric Apple ID. The description itself adds no parameter-level meaning, so the baseline of 3 applies because schema coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Read'), resource ('beta app review detail'), and scope ('for an app'), with the explicit GET route further clarifying the app-scoped lookup. It does not explicitly differentiate itself from the closely named sibling beta_app_review_details__get, so it stops short of full disambiguation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for an app' and the endpoint /v1/apps/{id}/betaAppReviewDetail imply when to use this tool, but there is no explicit guidance about alternatives or when not to use it. Notably, it does not mention that beta_app_review_details__get/list are the resource-scoped counterparts.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructtiveHint=false, and the description only repeats the read-only nature by saying 'List'. It adds no behavioral context beyond that, such as pagination behavior, filtering implications, relationship inclusion costs, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately states the resource, scope, and underlying endpoint. No wasted words or redundant detail are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The concise description combined with the fully documented schema and read-only annotations provides enough operational context for an agent to invoke the tool correctly. The only minor gap is an explicit statement about response shape or pagination behavior, though the schema's next_url and limit parameters strongly imply it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 100%, the input schema already documents all ten parameters, including filters, sort, pagination, and field selection. The description contributes no additional parameter meaning, so the schema-heavy 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 states a specific verb and resource: 'List the build uploads belonging to an app', and it reinforces the exact endpoint [GET /v1/apps/{id}/buildUploads]. This makes the operation distinguishable from 'get' siblings such as build_uploads__get and from apps__builds__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 gives a clear purpose, so an agent can infer when to call it: when build uploads for a particular app are needed. However, it provides no explicit guidance about when to prefer this over related tools like apps__builds__list or build_uploads__get, nor does it state any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read. The description adds only the 'by ID' constraint and endpoint, which is already obvious from the name and schema. It provides no additional behavioral context like response size or relationship 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?
Two short sentences, front-loaded with the action and resource, followed by the endpoint. Every word earns its place; no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-item GET with strong annotations and full schema coverage, the description is sufficient. It doesn't explain the return structure, but the resource name and selectable fields imply the response. Since no output schema is present, some ambiguity remains, but this is a low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, include, fields_appStoreReviewDetails) already documented in detail. The tool description adds no additional parameter semantics beyond the endpoint, so the baseline score 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?
The description clearly states the action (Read), the resource (App Store review detail), and the scope (one by ID). The endpoint `[GET /v1/appStoreReviewDetails/{id}]` reinforces this. It distinguishes from sibling tools like create/update/list by emphasizing it's a single-item read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance about when to use this vs alternatives. The 'by ID' phrasing implies it's for fetching a specific record, but there are no exclusions or alternative tool mentions. This is only implied usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, which convey the destructive and safe-to-retry nature. The description merely restates 'Delete' and adds the endpoint, providing no additional behavioral context such as whether deletion is permanent, what happens to associated data, or required permissions. It does not contradict the annotations but adds minimal transparency beyond them.
Agents need to know what a tool does to the world before 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, front-loaded sentence that states the action and resource immediately. The endpoint is appended in brackets without clutter. Every word earn its place, and there is no redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description is sufficiently complete. The annotations cover the destructive and idempotent behavior. The schema tells the agent where to get the ID. However, it does not provide contextual details about the resource's role in experiment treatments or any cascading effects, which would have made it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%: the single required parameter 'id' is described as 'ID from the matching list call.' The description itself does not add any further meaning to the parameter. Since the schema already explains the parameter's origin and purpose, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with the specific verb 'Delete' and clearly identifies the resource as an 'App Store version experiment treatment localization'. This directly states the tool's action and target, and it distinguishes this tool from sibling tools that create, get, or update the same resource. The inclusion of the HTTP DELETE endpoint reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this tool when you need to delete an App Store version experiment treatment localization. However, it does not explicitly state when NOT to use it, alternatives, or any prerequisites beyond the ID. There is no guidance on how this delete differs from other delete tools for related resources.
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 annotations already declare destructiveHint=true and idempotentHint=true, and the description adds no extra context beyond repeating 'Delete'. It doesn't disclose consequences like irreversibility or effects on related resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the endpoint, front-loaded and zero waste. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity (one parameter, no output schema) and strong annotations covering destructive/idempotent behavior, the description is complete enough. It could mention success/failure responses but that's not critical for this minimal delete operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a single 'id' parameter described as 'ID from the matching list call.' The tool description adds no additional parameter meaning, but the schema 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 explicitly states 'Delete an App Store version experiment treatment' with a specific verb and resource, clearly distinguishing it from sibling create/get/update variants. The endpoint is also provided for precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The delete action is clear, but the description does not explicitly state when to use it versus alternatives or mention any prerequisites like listing first. The usage is implied by the operation type and tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-read-only, non-idempotent operation, and the description is consistent. However, it adds no additional behavioral context like prerequisites, side effects, permissions, or expected response. It mostly restates the operation's purpose without disclosing hidden 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?
Two sentences, front-loaded with the verb and resource, and includes the endpoint. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool involves a nested JSON:API structure with required relationships (appStoreVersion), but the description does not mention the need to supply a relationship ID or what response to expect. With no output schema, this is a significant gap 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 description coverage is 100% (the body parameter has a description). The description enumerates locale-related fields (description, keywords, whatsNew, promotionalText), which adds mild semantic value, but the schema already defines all parameters, types, and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a new language (locale)') and the resource ('to an App Store version'), listing the fields included (description, keywords, what's new, promotional text). This distinguishes it from sibling operations like update, delete, or 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 when to use it (when adding a new localization) but does not explicitly mention alternatives or exclusions, such as using the update tool for existing localizations. It provides clear context but lacks when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds no additional context about response behavior, auth requirements, or side effects; it merely restates that it reads a resource. No contradiction exists, but no extra value is contributed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: one clear purpose statement and one endpoint reference. Both are concise and front-loaded, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description clearly identifies what the tool does and what it returns (the localization object). It does not explain the optional include/fields behavior, but that is fully documented in the schema. Given the read-only annotations and straightforward single-resource get, the description is sufficiently complete, though a bit more context about the include parameter could improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed descriptions for id and optional include/fields parameters. The tool description itself does not mention parameters or add semantics beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Read' and a specific resource 'one App Store version localization by ID.' It distinguishes from sibling tools like app_store_version_localizations__update, __delete, and list operations. The HTTP endpoint reinforces the resource identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single localization by ID, but does not explicitly state when to use this tool vs alternatives like listing localizations or using variant tools. No exclusions 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, and the description merely restates the delete action without adding context about consequences, irreversibility, auth requirements, or response behavior. No contradiction, but the description adds no behavioral information beyond the structured hints.
Agents need to know what a tool does to the world before 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, front-loaded sentence followed by the endpoint path. It contains no filler or redundant information, making it highly scannable and appropriately sized for a simple delete operation.
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 one-parameter delete with strong annotations (destructive, idempotent) and no output schema, the description is nearly complete. The resource and endpoint are clear, and the annotations cover the destructive nature. It could add a note about permanent deletion or the empty response body, but these are minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage: the only required parameter 'id' is described as 'ID from the matching list call.' The description itself adds no parameter-level detail, so the baseline of 3 is appropriate since the schema fully documents the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Delete an App Store version phased release' — a direct, specific verb plus resource. It is unmistakably distinct from the sibling create/update/get tools for phased releases, and the endpoint path reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is implied by the verb 'delete' and the resource name, but there is no explicit when-to-use guidance or mention of alternatives. With sibling tools like create/update, a note about when deletion is appropriate would improve the score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already mark the tool as readOnly, idempotent, and non-destructive. The description adds no additional behavioral context such as pagination behavior, required permissions, or response format details. It is essentially a restatement of the endpoint.
Agents need to know what a tool does to the world before 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 communicates the core functionality, with the endpoint path providing additional reference. No filler words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation, the description and schema together are adequate. The description answers what is listed, and the schema covers filtering, pagination, and field selection. However, no output schema exists, and the description does not explicitly describe pagination or response structure, but the schema's next_url parameter implies it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All six parameters have descriptions in the schema (100% coverage), so the description itself adds no parameter-specific information. The description's mention of 'belonging to an App Store version' aligns with the required 'id' but adds no new semantic detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('App Store version localizations'), and the scope ('belonging to an App Store version'), and includes the endpoint path. This distinguishes it from sibling tools like 'get' or 'create' for localizations.
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 use case: to list localizations for a specific App Store version, but it does not explicitly mention alternatives or when not to use it. There is no comparison with other list/get tools, so an agent might not know when to choose this over a related resource-specific list.
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 annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description merely restates that this is a read operation and provides the endpoint, but adds no additional behavioral context such as error handling, rate limits, permissions, or side effects. It provides minimal value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact single sentence plus the HTTP path, with the key action and resource front-loaded. There is no redundant information; every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one parameter and no output schema, the description sufficiently conveys the purpose and implies the return value (the app object). The schema provides the necessary ID context. However, it lacks an explicit statement about the response structure, which would be more critical if there were no output schema, but here the tool's simplicity makes it acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage for the single parameter is 100%, and the schema description 'ID from the matching list call' is clear and actionable. The tool description adds little beyond the schema, only clarifying that the ID belongs to a beta app localization. Baseline for high schema coverage is 3, and this description does not significantly enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies the resource as 'the app' for a beta app localization, clearly distinguishing it from sibling tools like beta_app_localizations__get (which gets the localization itself) and apps__get (which gets an app by ID). The HTTP path further confirms the exact 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?
The description implies usage by stating the resource relationship ('the app for a beta app localization'), but it does not explicitly state when to use this tool versus alternatives or mention any exclusions. No alternative tools are referenced. This falls under implied usage rather than clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it is a safe read operation. The description merely restates 'Read' and provides the endpoint, adding no extra behavioral context such as response format, error conditions, or relationship details. It does not go beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one practical sentence plus the endpoint reference. It is front-loaded with the verb 'Read' and immediately identifies the resource. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only get-by-ID operation, this description is mostly complete. It communicates the action and resource. However, since there is no output schema, a bit more detail about what the returned build includes could be helpful, but given the simplicity and strong annotations, it is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single parameter 'id' ('ID from the matching list call'), so the schema already carries the semantic weight. The description adds no additional parameter context, meeting 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 states a specific action ('Read the build') and the resource ('for a beta app review submission'), clearly distinguishing it from siblings like beta_app_review_submissions__get (which reads the submission itself) and builds__get (which reads a build by its own ID). The endpoint path reinforces the precise relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you have a beta app review submission ID and need its associated build. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/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 merely says 'Read' which adds no behavioral context beyond what annotations provide; it doesn't mention authentication requirements, rate limits, or return characteristics. Thus the description provides minimal behavioral disclosure beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the endpoint included, containing no redundant words or filler. It front-loads the operation ('Read') and the resource, making it both concise and immediately informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read operation with strong annotations, the description is mostly complete. It lacks explicit mention of the return type (the build object), but the tool name and description make it implicit. The endpoint and parameter guidance from schema cover the remaining context, so no major gaps exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the parameter 'id' described as 'ID from the matching list call.' The tool description itself adds no parameter detail, but the schema sufficiently explains the parameter's origin and purpose, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read the build for a beta build localization' with the specific GET endpoint. It specifies the resource (build) and its parent (beta build localization), and the verb 'Read' distinguishes it from modifying operations. The sibling tools like beta_build_localizations__get and builds__get are distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a beta build localization ID and need its associated build, but it does not explicitly state when to use it or mention alternative tools. There is no guidance on when not to use it (e.g., if you need the localization itself).
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, and destructiveHint=false, covering the safety profile. The description adds only the HTTP path and no additional behavioral context (e.g., pagination behavior, rate limits, or response structure). Score is adequate but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two clear pieces of information: the purpose and the HTTP endpoint. No unnecessary words, making it efficient and easy to parse.
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 6 optional parameters and no output schema, the description covers the essential purpose. However, given the lack of output schema and the variety of filters, a bit more context on pagination or typical usage would improve completeness, but it is still sufficient for a straightforward read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents each parameter's meaning and constraints. The description does not add any further semantic information beyond what the schema provides, meeting the baseline but not exceeding 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 verb 'List' and the resource 'beta build localizations', with the HTTP path appended. It unambiguously identifies the action and resource, and the name itself distinguishes from sibling create/delete/update/get tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., builds__beta_build_localizations__list, or more specific filter scenarios). No prerequisites, exclusions, or context for choosing between list endpoints 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=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description does not contradict these and adds the HTTP method context. No additional behavioral nuance (e.g., pagination defaults, rate limits) is provided, but with the annotations covering the critical safety aspects, the description is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at two sentences with no wasted words. It front-loads the core purpose and includes the HTTP endpoint for technical context. One could argue the endpoint is redundant with the tool's behavior, but it's not harmful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 13 parameters, no output schema, and is a simple list operation with rich annotations, the description is minimally adequate. It doesn't explain return value format or pagination behavior (e.g., how limit and next_url interact), but the schema covers parameters well. For a read-only list tool, this is acceptable but not exemplary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all 13 parameters thoroughly. The description adds no new semantic meaning beyond what the schema provides (e.g., it doesn't clarify edge cases or usage patterns for parameters like filter_app or filter_builds). Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List beta groups' which is a specific verb+resource combination. It distinguishes itself from sibling tools like beta_groups__create, beta_groups__get, beta_groups__delete, and beta_groups__update. The HTTP method hint reinforces the read-only 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 provides a minimal usage hint via the HTTP endpoint, but it does not explicitly state when to use this over other list tools (e.g., apps__beta_groups__list) or provide when-not-to-use guidance. No alternative tools are named.
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, and destructiveHint=false, so the safety profile is clear. The description adds the endpoint but no additional behavioral details (e.g., pagination behavior, default page size, or relationship semantics). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the action and scope, the second gives the REST endpoint. Every word is purposeful, and the information is front-loaded. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description is sufficient: it states what is listed and provides the endpoint. Parameters are documented in the schema, and annotations cover safety. Minor missing context like pagination defaults or relationship constraints are not critical here, but the description could have been slightly richer.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all four parameters, including id, limit, next_url, and fields_apps. Since schema coverage is 100%, the description does not need to add parameter details. The description itself adds no extra parameter semantics, which is acceptable given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid 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 apps, and identifies the specific resource scope: belonging to a beta tester. The endpoint reference reinforces the target. This distinguishes it from sibling tools like beta_testers__builds__list or beta_testers__beta_groups__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 usage guidance is provided. The description does not indicate when to use this tool over alternatives, nor does it mention any prerequisites or exclusions. Given the many sibling list tools, this is a missed opportunity for orienting the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read-only operation. The description adds the specific relationship and GET endpoint but does not disclose pagination behavior, return format, or permission requirements, providing only modest additional context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with the endpoint reference, containing no redundant or filler information. It is front-loaded and immediately communicates the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-only list operation, the description, annotations, and schema are largely sufficient. Pagination and field selection are covered by the schema parameters, and the 'List' semantics imply a collection response, though the absence of an output schema means the response shape is not explicitly disclosed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides clear descriptions for all four parameters (id, limit, next_url, fields_betaGroups) with 100% coverage, so the description does not need to compensate. The description itself adds no parameter-specific detail, so the baseline score 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?
The description uses a specific verb 'List' with the resource 'beta groups' and clearly scopes them to 'belonging to a beta tester', which distinguishes it from the inverse sibling tool beta_groups__beta_testers__list. The endpoint URL further reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives such as beta_groups__beta_testers__list, nor does it mention any exclusions or prerequisites. The intended context is only implied by the tool name and the phrase 'belonging to a beta tester', which is not sufficient guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds only the endpoint, which is already implied by the tool name, and provides no additional behavioral context such as include behavior or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: a single sentence plus the endpoint. Every word earns its place, and the endpoint provides precise routing 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?
For a simple read operation with annotations and a fully self-describing schema, this description is sufficient. The endpoint clarifies the exact resource, and the tool's role is understandable in the context of sibling tools, though a note about the 'include' parameter's purpose would have made it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'include' described in the schema. The description adds no parameter-level detail, but the schema carries the burden, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Read the build') and the resource ('for a build beta detail'), and the endpoint path makes the exact scope unambiguous. It is distinct from sibling tools like builds__build_beta_detail__get, which performs the inverse relationship.
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. The sibling builds__build_beta_detail__get is the inverse relationship, but the description does not mention it or any other context for choosing this endpoint.
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 and idempotentHint, and the description adds no new behavioral context such as error behavior, response format, or rate limits. It merely restates the read operation without contradicting 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 one concise sentence plus the endpoint, with no filler or redundant wording. It is front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-get tool with a well-described schema and safety annotations, the description is largely sufficient. It does not spell out return values, but the fields_buildBetaDetails parameter implies possible attributes, and the schema notes the ID source.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters have descriptions in the schema (100% coverage), so the description adds no additional parameter meaning. The schema already explains the id, include, and fields parameters 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 uses a specific action 'Read' and a clear resource 'one build beta detail by ID', which unambiguously differentiates this from listing or updating tools. The endpoint reference reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an ID is known, but it does not explicitly mention when not to use the tool or compare it with siblings like build_beta_details__list or builds__build_beta_detail__get. Guidance is only implicit, not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the operation as read-only, idempotent, and non-destructive. The description adds no behavioral details such as authentication, rate limits, pagination, or response format, and mostly restates the scope already visible in the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence followed by the API endpoint. No redundant information, front-loaded with the verb and immediate resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is usable given the clear scope and schema descriptions; pagination is indirectly covered by limit/next_url parameters. However, no output schema is provided and the description does not explain the response shape or pagination behavior, leaving minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all five parameters, including id, limit, next_url, include, and fields. The description offers no additional parameter semantics beyond what the schema provides, so a baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' with a specific resource scope ('beta App Clip invocations belonging to a build bundle'), clearly differentiating it from sibling mutation endpoints like beta_app_clip_invocations__update and beta_app_clip_invocations__delete. The endpoint is included for reference.
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 should be used to retrieve all beta App Clip invocations for a given build bundle, but it does not explicitly mention alternatives or exclusion criteria. Sibling tools like beta_app_clip_invocations__get are not referenced, leaving the agent to infer the difference.
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, and destructiveHint=false. The description adds only the HTTP endpoint and does not contradict annotations. It provides no extra behavioral context such as pagination, authentication needs, or rate limits beyond what the schema already covers.
Agents need to know what a tool does to the world before 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 clear sentence with an inline endpoint reference. No wasted words; every element serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a listing tool with five well-documented parameters and safety annotations, the description is sufficient to convey the core action and scope. The lack of an output schema is compensated by the implicit return of diagnostic signatures, and the schema covers filtering and field selection. However, it omits any note about pagination or expected response shape, though this is minor for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters (id, limit, next_url, filter_diagnosticType, fields_diagnosticSignatures) already have descriptions. The tool description adds no parameter-level detail beyond what the schema provides, matching the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('List') and the resource ('diagnostic signatures belonging to a build'), matching the endpoint. It distinguishes from siblings like diagnostic_signatures__logs__list, which lists logs rather than signatures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives such as builds__list or diagnostic_signatures__logs__list. The context is implied by the resource, but there is no explicit when-to-use or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the endpoint information but provides no additional behavioral context such as pagination behavior, default limit, or relationship to beta groups. With annotations covering safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is direct and informative, with the endpoint path as a helpful reference. No wasted words; every part adds value. Fits the conciseness ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with good annotations and full schema coverage, the description along with structured data is nearly complete. It lacks explicit pagination details beyond the schema's parameter descriptions, but the 'next_url' parameter hints at pagination. No output schema, but return value for a list is reasonably inferred. Slight gap in not explaining relationship to beta groups, but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the 3 parameters. The description mentions the build ID as 'ID from the matching list call' in the schema, which adds a bit of context, but the description itself does not elaborate beyond schema. Baseline 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'individual testers belonging to a build', with the HTTP endpoint. It distinguishes from siblings like builds__individual_testers__add/remove and builds__beta_groups__list, but does not explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the read operation for individual testers on a build, and the endpoint path clarifies the resource. However, it does not explicitly state when to use this vs alternatives like builds__beta_groups__list or when not to use it. The context is clear but no exclusions or alternative guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds the HTTP method and path, which is slightly beyond annotations but does not disclose additional behavioral traits such as error handling, authentication requirements, or response format. 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?
One concise sentence plus endpoint. No filler words, front-loaded with the action. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one required parameter, no output schema, clear annotations), the description is largely adequate. However, it does not explain what a 'pre release version' is or what the response contains, which would be helpful given no output schema. Still, the resource name implies the return value, so it earns a 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% (the 'id' parameter has a description: 'ID from the matching list call.'). The description adds no further parameter semantics, 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?
The description uses a specific verb 'Read' and clearly identifies the resource: 'pre release version for a build'. It includes the endpoint, which clarifies the exact relationship being accessed, distinguishing it from sibling tools like builds__get or pre_release_versions__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 is provided about when to use this tool versus alternatives. It does not mention related tools (e.g., builds__app__get for app relationship) nor any prerequisites or context. The only clue is the endpoint, but explicit usage guidance is missing.
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=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds only the endpoint and does not disclose non-obvious behaviors such as field-selection size implications (which appear only in the schema) or any other context. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences deliver the purpose and the endpoint with no redundant text. Information is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with full schema coverage and strong annotations, the description is sufficient for selection and invocation. It includes the essential purpose and endpoint, though it doesn't mention relationships to the parent build upload or list workflows—but these are not necessary given the schema and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description adds no parameter semantics beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and identifies the resource ('one build upload file') and the access pattern ('by ID'). Including the HTTP method and endpoint '[GET /v1/buildUploadFiles/{id}]' further disambiguates from sibling tools like create/update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The statement implies usage for reading a single file when the ID is known, and the schema hints the ID comes from a list call. However, it does not explicitly state when to use this over list variants or other related tools, nor does it provide exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=false and destructiveHint=true, and the description merely repeats the delete concept without adding extra behavioral context such as irreversibility, side effects on associated files, or behavior when the ID doesn't exist. It adds no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the HTTP endpoint, containing zero wasteful words. It is appropriately front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and strong annotations, the description is nearly complete. It clearly identifies the resource and the method, and the schema covers the ID. However, it could have mentioned that the deletion is permanent or that the upload must already exist, though the destructiveHint annotation partially fills this gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single parameter, and the description adds no additional parameter information. The schema description ('ID from the matching list call') provides the necessary context, so the baseline score 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?
The description clearly states 'Delete a build upload' with a specific verb and resource, and it is immediately distinguishable from sibling tools like build_uploads__create and build_uploads__get. The inclusion of the HTTP DELETE method reinforces the action.
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 what the tool does but gives no explicit guidance on when to use it versus alternatives. The schema parameter description ('ID from the matching list call') implies a prerequisite, but the description itself doesn't mention exclusions or alternative tools for handling build uploads.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, and the description adds no additional behavioral context such as irreversibility, required permissions, or side effects. The description is essentially a restatement of the tool's name.
Agents need to know what a tool does to the world before 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 followed by the endpoint. It is front-loaded with the action verb and contains no unnecessary content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter, the description combined with the annotations (destructive, idempotent) and schema provides sufficient context. No output schema exists, but that is typical for delete operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the 'id' parameter described as 'ID from the matching list call.' The description itself adds no parameter details, so it relies on the schema, yielding a baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('end user license agreement'), and includes the HTTP endpoint for full clarity. This distinguishes it from sibling tools like create, get, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The tool's usage is implied by its name and description, but there is no explicit guidance on when to use it versus alternatives (e.g., update or create). No prerequisites or exclusions are mentioned beyond the schema's note that the ID comes from a list call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the description's 'Read' is consistent but adds no extra behavioral context beyond those annotations. It does not describe return format, relationship inclusion, or other behaviors, leaving the annotations to cover the safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb 'Read,' and closes with the endpoint path. It is concise with no wasted words, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description adequately states the action and resource. The schema covers parameters and annotations cover behavior, so the lack of an output schema note is acceptable, though mentioning that `include` and `fields` control response content would improve completeness slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (`id`, `include`, `fields_preReleaseVersions`) having detailed descriptions. The tool description itself adds no parameter information, but since the schema fully documents them, the baseline score 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?
The description uses the specific verb 'Read' and identifies the resource 'pre release version' with scope 'by ID,' which clearly distinguishes it from sibling tools like pre_release_versions__list and pre_release_versions__builds__list. The endpoint path reinforces the action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as after a list call or when related records are needed. It lacks context, exclusions, or mention of the matching list call, which is only referenced in the schema for the 'id' parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnly=false, destructive=false, and idempotent=true. The description adds the HTTP method PATCH and endpoint, which implies partial update semantics, but does not disclose additional behaviors like error conditions, validation, or response format. This is consistent but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single action phrase plus the endpoint. No wasted words, front-loaded with the action, and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich schema and annotations, the description is mostly sufficient but omits any mention of return value or update semantics beyond the endpoint. A slightly more detailed statement would make it more complete, but the current level is adequate for an update operation with full schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for 'id' ('ID from the matching list call') and 'body' ('JSON:API request body'). The description does not add further parameter semantics, so the 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?
The description clearly states a specific action (Update) on a specific resource (routing app coverage), and the verb 'update' distinguishes it from siblings like create, delete, and get. The inclusion of the HTTP method and path reinforces the intent.
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 to update versus create/delete, or any prerequisites or exclusions. It is silent on usage context, making it minimally useful for choosing between related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the endpoint and ID-based retrieval, but no additional behavioral details such as rate limits, auth requirements, or response characteristics. It is consistent with 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 a single sentence plus the HTTP endpoint, with no filler or redundant content. Every word contributes to understanding the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool, the description, combined with the rich schema and safety annotations, is complete. The description states the function, the schema explains all parameters, and annotations cover side effects. No output schema is provided, but for a GET resource the return is implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (id, include, fields_alternativeDistributionPackages) having descriptive text. The description itself does not add parameter-level meaning, so the 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?
The description uses the specific verb 'Read' and identifies the resource as 'one alternative distribution package by ID', making the tool's purpose unambiguous. It clearly distinguishes this from creation or listing tools among the siblings, even without naming alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives like listing packages or getting package versions. It implies the prerequisite of having an ID but does not clarify where the ID comes from or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the endpoint path and the phrase 'belonging to' but does not disclose additional behavioral traits like pagination or filtering specifics, which are already in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus the endpoint path, front-loaded with the action and resource. Every word earns its place, with no filler or unnecessary detail.
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 rich schema and annotations, the description provides the basic purpose and endpoint, which is sufficient for a simple list operation. However, it does not mention filtering, pagination, or relationship inclusion options that are available in the schema, nor does it reference alternatives, so it is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters already have descriptions. The tool description does not add any additional semantics beyond the schema, so the baseline score 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?
The description uses a specific verb ('List') and clearly identifies the resource ('versions belonging to an alternative distribution package'), with the endpoint path further clarifying the exact operation. It also distinguishes from sibling tools like alternative_distribution_package_versions__deltas__list and __variants__list, which focus on different sub-resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing versions of an alternative distribution package, but it does not provide explicit guidance on when to use this tool versus alternatives such as the deltas or variants list endpoints. No exclusions or scenarios 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=false, idempotentHint=true, destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context beyond saying 'Update', which aligns with annotations. No contradiction; it simply doesn't add additional nuance (e.g., what fields are affected).
Agents need to know what a tool does to the world before 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 one concise sentence plus the HTTP endpoint. It is front-loaded with the action and resource, contains no fluff, and the endpoint adds precise technical context. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, a nested body, and no output schema, the schema covers invocation details. However, the description does not provide additional context about when to use this update (e.g., after uploading an image, updating checksum) or any domain-specific behavior. It is minimally sufficient but not richly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'id' is described as 'ID from the matching list call' and 'body' as 'JSON:API request body'. The description adds no extra parameter meaning beyond the schema, 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 'Update an App Clip advanced experience image' with a specific verb and resource, and includes the HTTP endpoint [PATCH /v1/appClipAdvancedExperienceImages/{id}]. This distinguishes it from sibling create, get, and delete operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: it is an update tool for App Clip advanced experience images. However, it provides no explicit guidance on when to use it vs. alternatives (e.g., when not to use it, or prerequisites like existing image ID). The purpose is clear, but selection context is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a mutating (readOnlyHint=false), idempotent, non-destructive operation. The description adds the PATCH verb and endpoint but no additional behavioral context such as side effects or required authorization. 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?
A single sentence that is front-loaded with the action and resource, followed by the endpoint reference. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, but without an output schema the description doesn't explain what the response looks like. The minimal description relies heavily on schema and annotations; it's adequate but leaves room for more context 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?
Schema description coverage is high (100%), with 'id' and 'body' documented. The description adds no extra parameter meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an App Clip App Store review detail' uses a specific verb and resource, clearly distinguishing it from sibling create and get tools. Including the PATCH endpoint further clarifies the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for modifying an existing review detail, but provides no explicit guidance on when to use it versus create/get alternatives. It also doesn't mention prerequisites like obtaining the ID from a list call, though the schema does.
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, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond the resource scope ('belonging to an App Clip'). It does not mention pagination, rate limits, or response format, but given the annotations, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource. It includes the endpoint reference without wasted words. Every element serves a clear purpose, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 8 parameters and no output schema, the description is functional but minimal. It does not explicitly state that the result is a paginated list or that include/filter options are available, though these are implied by the schema. Given the schema covers parameter details, the description is adequate but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all parameters including filters, pagination, and includes. The description adds no additional parameter semantics, but it is not needed to compensate for missing schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('App Clip advanced experiences belonging to an App Clip'). It distinguishes this from sibling get/create/update operations by specifying the collection relationship with the parent App Clip, and includes the endpoint path for additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is a list operation for a specific parent resource, but it does not explicitly mention when to prefer this over related tools like app_clip_advanced_experiences__get or app_clip_advanced_experiences__create. No alternatives or exclusions are stated, though the resource scoping is clear.
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, and destructiveHint=false, covering the safety profile. The description adds resource scoping and the endpoint but does not disclose additional behavioral traits such as pagination, relationship inclusion costs, or response characteristics. 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 a single, front-loaded sentence with no filler, plus an endpoint reference. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter list tool with no output schema, the description is minimal. It states the core purpose but leaves pagination, include relationships, sorting, and filtering to the schema descriptions. The schema is detailed, but the description itself does not offer enough standalone context for an agent to assess trade-offs against sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already explains all parameters. The description's 'belonging to an app' reinforces the required id parameter but adds no new semantics for the other eight parameters. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('List'), resource ('in-app purchases (v2)'), and scope ('belonging to an app'), and includes the REST endpoint. This clearly distinguishes it from sibling list tools such as apps__promoted_purchases__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 phrase 'belonging to an app' implies the tool should be used when you need an app's IAPs, but there is no explicit guidance about when to use this versus alternatives, nor any when-not-to-use context. Usage is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, and non-destructive behavior, so the bar is lower. The description adds the app-scoping context and HTTP GET method, but does not disclose pagination, default ordering, or what response shape to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with no fluff; the action and endpoint are front-loaded. Every clause adds orientation.
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?
Schema and annotations cover parameters and safety, but without an output schema the agent still has to infer response shape and pagination behavior. It also lacks guidance on how this endpoint relates to review_submissions__list or beta_app_review_submissions__list.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 descriptions cover 100% of parameters and are already detailed (id aliases, include cost note, fields size warning). The description itself adds no parameter-level meaning beyond that, which lands at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb ('List') and resource ('review submissions belonging to an app'), reinforced by the endpoint path. The app scoping distinguishes it from sibling list tools like review_submissions__list and beta_app_review_submissions__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?
It implies use when you have an app identifier and need that app's review submissions, but it does not explicitly mention alternatives or when not to use this route. With several review-related sibling list endpoints, explicit routing would be clearer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No contradiction: 'Read' and the GET method align with readOnlyHint=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description only adds the endpoint path; it does not disclose what happens when no grace period is configured or what auth scope is required, so the annotations carry the safety profile and the description adds little 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?
An eight-word sentence with the action verb front-loaded and a compact bracketed endpoint. Every token earns its place; there is zero filler or repetition of the tool name.
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?
Complexity is low (one fully documented parameter, safety covered by annotations), so the description is nearly sufficient. The gap is that with no output schema, the description gives no hint about the response shape — whether the grace period is a duration, a date, or in what units — and offers no domain context about when a grace period applies.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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% — the single id parameter is fully documented ('App name, bundle ID (com.example.app) or numeric Apple ID'). The description contributes no parameter-level meaning, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and names the exact resource ('subscription grace period for an app'), then confirms it with the endpoint [GET /v1/apps/{id}/subscriptionGracePeriod]. Among hundreds of siblings there is no other grace-period tool, so the resource name alone distinguishes it from apps__get and apps__subscription_groups__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?
Usage is implied by the verb+resource ('Read the subscription grace period') but never made explicit — no when-to-use conditions, no exclusions, no named alternatives. For a single-resource getter with no competing sibling this is acceptable, yet the guidance is entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (not read-only, idempotent, not destructive). The description adds the HTTP method PATCH, which implies partial update semantics, and the schema shows the updatable attributes. It does not, however, explain the implications of setting nullable attributes like uploaded or sourceFileChecksum, but with annotations present the bar is lower.
Agents need to know what a tool does to the world before 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 verb phrase and one endpoint specification. It is front-loaded with the action and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately complex update with a nested JSON:API body, the schema covers parameter structure thoroughly. However, the description does not explain response format (no output schema) nor the exact effect of setting attributes like uploaded or sourceFileChecksum, leaving some gap given the tool's mutation nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-described: id from the matching list call and body as a JSON:API request body referencing the Apple schema. The description itself adds no extra parameter context, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update an App Store review attachment') with a specific verb and resource, and distinguishes it from sibling create/delete/get tools. The explicit HTTP method PATCH and URL template remove any ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for modifying an existing attachment, and the id parameter schema says 'ID from the matching list call,' giving a needed prerequisite. However, it does not explicitly state when to use this versus create/delete alternatives or mention any preconditions like the attachment's upload state.
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, and destructiveHint=false, covering the safety profile. The description adds the 'by ID' scoping and the endpoint path, but does not disclose additional behavioral details such as auth requirements, rate limits, or relationship inclusion effects. This is acceptable given the annotation coverage but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the action and resource, and includes the endpoint path. There is zero waste; every word 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?
The tool is a simple read-by-ID operation with fully documented parameters and clear annotations (read-only, idempotent). No output schema is present, but the description and schema together provide sufficient context for an agent to understand and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with all three parameters (id, include, fields_appStoreVersionExperimentTreatmentLocalizations) fully described in the input schema. The description adds no additional parameter meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('one App Store version experiment treatment localization by ID'). It is distinct from sibling tools like create, delete, or update operations, and the endpoint path reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, no mention of prerequisites, or any exclusions. It simply states what the tool does without contextual usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds the HTTP method PATCH, which hints at partial update semantics, but it does not disclose other behavioral details such as required permissions, whether changes are reversible, or what happens to unspecified fields. With annotations carrying the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus the endpoint path. It is front-loaded with the action and resource, contains no redundant information, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with detailed schema and annotations, the description is minimally adequate. However, there is no output schema, and the description does not explain response behavior or any side effects beyond 'update'. This leaves some ambiguity for the agent, though the schema fills most gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id described as 'ID from the matching list call' and the body as a JSON:API request. The description itself adds no parameter-specific meaning, so the baseline score 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?
The description clearly states 'Update an App Store version experiment treatment' with a specific verb and resource. The endpoint path [PATCH /v1/appStoreVersionExperimentTreatments/{id}] further confirms the action, and the name distinguishes it from sibling create/delete/get tools for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied: the tool updates an existing treatment. However, no explicit guidance is given on when to use it versus alternatives, nor does it mention prerequisites (e.g., that the id must come from a list call, though the schema provides that hint). There are no exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the endpoint and the read verb, but no additional behavioral context such as rate limits, auth needs, or effects of the include parameter. 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 a single concise sentence with the endpoint, front-loaded with the action and resource. No unnecessary words or repetition.
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 strong annotations, full schema coverage, and no output schema, the description is sufficient. It clearly states the resource being read and the endpoint, and the schema covers parameter details. No additional context is needed for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters (id and include) are fully described in the schema. The description adds no extra meaning beyond the endpoint path, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Read') on a specific resource ('the Game Center app version') tied to an App Store version, distinguishing it from sibling tools like app_store_versions__get or builds__app_store_version__get. The endpoint path reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage 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, no exclusions, and no mention of prerequisites beyond the schema. The description merely states what the tool does without any contextual usage advice.
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. The description adds no behavioral context beyond restating the read operation and endpoint. It does not disclose return format, pagination, or any operational details, so the value is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the purpose, followed by the endpoint. There is no redundant or filler content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, with one required parameter and good annotations. However, there is no output schema and the description does not explain what the response returns or that a prior list call is needed (though the schema hints at this). It meets the minimum bar but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'include' having clear descriptions. The tool description adds no parameter-related information beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Read'), the resource ('routing app coverage'), and the scope ('for an App Store version'). It also includes the endpoint, which unambiguously identifies the operation. This distinguishes it from sibling tools like routing_app_coverages__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: this tool reads routing app coverage for a specific App Store version. It implies usage is for fetching a related resource, and the endpoint confirms the relationship. However, it does not explicitly mention alternatives or when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a write operation (readOnlyHint=false), non-idempotent, and non-destructive. The description adds the key constraint that testers must already exist ('existing'), which is useful. It does not, however, disclose what happens if a tester is already in the group or mention any required permissions, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that captures the essential purpose, followed by the endpoint reference. No redundant information is included. It is appropriately concise for the tool's simplicity.
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 sufficient for a straightforward relationship-add operation, especially with detailed schema and annotations. However, it does not explain the response (no output schema exists), error conditions, or whether duplicate additions are allowed. Given the complexity of the nested body and the potential for user errors, a bit more context on expected outcomes would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters well-described: 'id' is the group ID from a matching list call, and 'body' is a JSON:API request body with a data array of tester IDs. The description repeats only the high-level concept of adding existing testers, which aligns with the schema. No additional parameter semantics are provided beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Add existing beta testers to a TestFlight group', specifying the verb, resource, and target. The included endpoint further clarifies the operation. It distinguishes from siblings like beta_groups__beta_testers__remove and beta_groups__builds__add by explicitly mentioning beta testers and the group relationship.
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 its use case: when you need to add existing beta testers to a specific TestFlight group. However, it does not provide explicit guidance on when not to use it, such as when creating new testers (beta_testers__create) or when adding groups to testers (beta_testers__beta_groups__add). The usage context is clear but undocumented alternatives are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is known. The description adds the HTTP DELETE method, but does not disclose consequences (e.g., lost tester access) or reversibility beyond what annotations imply. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence plus the endpoint placeholder. No redundant information or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relationship-unlink operation, the combination of schema and annotations provides adequate context. However, the schema marks body as optional at the top level, and the description does not clarify whether a body is required to specify which builds to remove, which could confuse the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with meaningful descriptions: id is explained as coming from a list call, and body references the Apple schema. The description itself adds no additional parameter meaning, but the schema carries the load, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Unlink') and resource ('builds from a beta group'), and the HTTP DELETE endpoint clarifies the action. This clearly distinguishes it from the reverse operation (builds__beta_groups__remove) and the add counterpart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for unlinking builds from a beta group, and the 'ID from the matching list call' hint suggests a workflow. However, it does not explicitly mention when to prefer this tool over the reverse sibling (builds__beta_groups__remove) or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds only the basic action ('Unlink') and the endpoint, with no additional details about effects, reversibility, or prerequisites. This meets the lower bar expected when annotations are present but does little to enrich 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?
The description is one concise sentence plus the endpoint, with zero wasted words. It immediately communicates the action and the target resource, fitting the standard of effective front-loading.
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 presence of a nested body schema and annotations covering destructive/idempotent behavior, the minimal description is mostly sufficient. However, it does not clarify whether the body is truly optional and what happens if it is omitted (e.g., unlink all groups), which could mislead the agent. This slight gap prevents a higher score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: both 'id' and 'body' have descriptive schema entries, including the note 'ID from the matching list call' and the Apple schema reference. The description itself adds no parameter-level information, so it appropriately relies on the schema's high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Unlink') and clearly identifies the resource ('beta groups from a beta tester'), which precisely distinguishes it from sibling tools like beta_groups__beta_testers__remove (which removes testers from a group). The included HTTP endpoint further clarifies the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the action, but it does not explicitly mention when to use this tool versus alternatives, such as beta_groups__beta_testers__remove. No exclusions or alternative tool names are provided, so the agent must infer from the naming convention.
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 behavioral safety is clear. The description adds minimal extra behavioral context (just the HTTP method and endpoint), but with strong annotations the bar is lower. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (two brief sentences including the URL). Every word is necessary and no filler exists. It's front-loaded with the core action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 13 parameters and no output schema, the description is somewhat lacking. It doesn't explain return values or common usage patterns. However, the strong annotations and fully described schema parameters partially compensate. An agent might need to infer pagination and filtering behavior from parameter names alone, which could be better explained.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 every parameter has a description. The tool's description does not add any extra meaning beyond the schema; it relies entirely on the structured field descriptions. Baseline is 3 because the schema does the heavy lifting, and the description adds no compensation for the lack of richer param context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List beta testers' with the resource and action, and the URL path [GET /v1/betaTesters] reinforces it. It sufficiently distinguishes itself from siblings like beta_testers__get or beta_testers__create, though it does not explicitly differentiate from other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description itself provides no guidance on when to use this tool vs alternatives or any context about prerequisites. However, the annotations (readOnlyHint, idempotentHint, destructiveHint) imply it is safe for read-only queries, and the parameter schema includes filtering and pagination hints that an experienced agent could infer usage. An explicit usage note is missing.
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 disclose that the tool is not read-only, is idempotent, and is not destructive. The description adds no behavioral context beyond the operation's name, such as whether this replaces an existing declaration or any required app state. There is 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 one succinct sentence followed by the endpoint. Every word contributes, 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?
The tool is a simple relationship setter with annotations and full schema coverage, but the description omits potential side effects (e.g., replacing current declaration) and prerequisites. No output schema exists, and the response behavior is not mentioned, so there is room for more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; both id and body include descriptions. The tool description adds no additional parameter semantics, and the body description only references an external Apple schema. A baseline of 3 is appropriate given the 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 the action ('Set') and the resource ('app encryption declaration linked to a build'), and includes the endpoint. This differentiates it from the sibling getter builds__app_encryption_declaration__get.
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 assigning an app encryption declaration to a build, but it does not explicitly mention alternatives or when not to use. The schema's id description ('ID from the matching list call') provides a minor prerequisite hint, but the description itself lacks explicit usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false and provide no safety signals, so the description carries the burden. The endpoint path and verb indicate a non-destructive write operation that modifies a relationship. However, it does not disclose whether the link is additive or replaces existing links, nor does it mention response behavior or side effects. It adds the endpoint context beyond annotations, but still leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences—one human-readable statement and one endpoint reference. Every word earns its place, with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple relationship add, and with full schema coverage it is fairly self-contained. However, with no useful annotations and no output schema, the description does not cover potential nuances like whether linking replaces existing groups, required ordering, or error conditions. It is minimally viable but lacks contextual depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: 'id' is clearly described as 'ID from the matching list call' and 'body' as the JSON:API request body. The description adds no parameter-specific meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Link' with the resources 'beta groups' and 'build', clearly targeting the relationship creation. The endpoint path [POST /v1/builds/{id}/relationships/betaGroups] further disambiguates the operation, and it stands apart from sibling tools like builds__beta_groups__remove.
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 establishing a relationship but does not explicitly state when to use this over alternatives (e.g., builds__individual_testers__add) or provide exclusions. The endpoint and verb 'Link' suggest the operation, but there is no explicit guidance on contexts 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 this as a safe, idempotent read operation (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the description doesn't need to repeat safety. It adds the endpoint but does not disclose additional behavior such as pagination handling or response structure, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus endpoint, front-loading the verb and resource with no extraneous information. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple, and the schema and annotations cover parameters and safety. However, with no output schema, the description does not explain what the response contains or how pagination via next_url works, leaving a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter having a description (e.g., 'ID from the matching list call', 'filter by attribute platform'). The tool description adds no additional parameter semantics beyond the schema, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('perf power metrics belonging to a build'), and includes the endpoint. This distinguishes it from app-level metric tools like apps__perf_power_metrics__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 use when you need metrics for a specific build, but does not explicitly state when to prefer this over alternatives such as apps__perf_power_metrics__list. No exclusions or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false. The description adds no new behavioral context—it merely restates the action. No mention of response format, errors, or performance characteristics beyond what the schema hints at.
Agents need to know what a tool does to the world before 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, front-loaded sentence with the endpoint included. No filler words or redundant information; it is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-by-ID operation with good schema coverage and safety annotations, the description is sufficient. It could hint at what the response contains, but the tool name and endpoint make the return type predictable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions fully cover both parameters: 'id' explains it comes from a list call, and 'fields_accessibilityDeclarations' explains selective attribute returns and the 200KB size caveat. The tool description adds no parameter-specific 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 uses a specific verb ('Read') and clearly identifies the resource ('one accessibility declaration by ID'). The endpoint path adds further precision and distinguishes it from list/create/update/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage context is clear: use this when you have an accessibility declaration ID and need a single record. It does not explicitly state alternatives or when-not-to-use, but the ID-based scope is self-evident.
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 description adds no behavioral information beyond what the annotations already state: destructiveHint=true and readOnlyHint=false. It doesn't disclose consequences like permanent deletion, auth requirements, or error behavior. With annotations already covering the safety profile, the description misses an opportunity to add meaningful 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 a single sentence with the specific action and endpoint, front-loaded and free of irrelevant details. Every word earns its place. It is an excellent example of concise, structured documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one fully-documented parameter, the description plus schema and annotations provide sufficient context. It doesn't mention return values or error handling, but no output schema exists and the operation is straightforward. A slightly richer note on permanence would make it fully complete, but it is adequate as-is.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameter (id) with a useful description ('ID from the matching list call'). The tool description does not add any parameter-specific semantics, so the baseline score of 3 applies. No additional clarification is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('alternative distribution domain'), making it distinct from sibling list, get, and create tools. Including the HTTP DELETE endpoint reinforces the specific operation. It fully defines the tool's purpose in a concise manner.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: whenever an alternative distribution domain needs to be deleted. It doesn't explicitly mention alternatives or exclusions, but the simple CRUD nature makes the usage obvious. The schema's 'ID from the matching list call' hints at the prerequisite of a prior list call.
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, and destructiveHint=false, covering the safety profile. The description adds contextual detail about verified domains and the marketplace scenario but does not disclose additional behavioral aspects such as pagination, rate limits, or response formats beyond what the schema implies. 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 a single, information-dense sentence followed by the endpoint path. Every word contributes meaning, with no filler or redundancy. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with three optional params and no output schema, the description covers the purpose, scope, and context. The schema describes the parameters and available fields. The only minor gap is that it doesn't explicitly describe the response shape, but the field list and list semantics make this inferable. Overall, it is complete enough for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 descriptive comment (limit, next_url, fields). The description does not elaborate on parameters beyond the endpoint, so it adds no extra semantic value. Baseline 3 applies because the schema fully documents the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'domains verified for EU alternative distribution', with an explanatory clause distinguishing it from App Store distribution. The endpoint path is included, and the name itself differentiates this list operation from get/create/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context (EU alternative distribution, marketplace vs App Store) that implies when to use it, but it does not explicitly mention alternatives or when not to use it. For example, it doesn't say 'use the get endpoint for a single domain.' Sibling names hint, but the description itself lacks explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds no further context about irreversible changes or side effects, but it doesn't contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the HTTP endpoint, containing no filler. It's efficiently front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete-by-ID tool, the description, schema, and annotations are sufficient. The schema provides the ID source, and annotations cover destructive behavior. Could mention permanence, but destructiveHint already communicates it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'id' parameter has 100% schema description coverage with a helpful hint about sourcing it from a list call. The description text itself doesn't add parameter details, so the 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?
The description clearly states the action 'Delete' and the resource 'alternative distribution key', making its purpose obvious. It distinguishes itself from sibling tools like list and create by specifying the delete operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly provide usage guidance or alternatives, though the schema's ID description ('ID from the matching list call') implies a typical flow from list to delete. There's no explicit when-not or alternative tool mention.
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, and destructiveHint=false, so the agent knows this is a safe read. The description adds the endpoint and 'by ID' but no further behavioral traits such as error handling or response size implications. The schema's fields parameter description notes the 200 KB concern, but that is not in the main description. 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 a single concise sentence that states the action and resource, followed by the endpoint. It is front-loaded, contains no filler, and every element is useful.
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-by-ID operation with complete schema coverage and read-only annotations, the description is adequately complete. It names the resource, method, and endpoint. It could optionally mention the relationship to the list call or that fields controls response size, but those are covered in the schema. The tool's simplicity makes a one-line description mostly sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (id and fields) already described in the schema, including the 'ID from the matching list call' and the 200 KB warning. The main description does not add parameter-specific meaning, and per the rubric, high schema coverage yields a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read one alternative distribution package variant by ID,' providing a specific verb, resource, and scope. It also includes the REST endpoint, making the purpose unmistakable. The resource is clearly distinct from sibling get tools like alternative_distribution_package_versions__get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a single variant by ID, but it does not explicitly state when to prefer this tool over the corresponding list tool (e.g., alternative_distribution_package_versions__variants__list) or other alternatives. The schema's id parameter mentions 'ID from the matching list call,' but the main description lacks this contextual 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 mark this as readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds minimal context beyond that—it specifies the HTTP endpoint and the 'belonging to' relationship—but it does not disclose additional behavioral traits like pagination behavior, response format, or any required authentication. Given the annotations cover safety, this is an adequate but not rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, one sentence, and front-loaded with the action ('List the deltas'). It also includes the API endpoint in brackets, which is useful for an agent reading API documentation. There is no redundant phrasing or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with no output schema, the description is sufficient for invocation. It clearly identifies the resource and its parent ('alternative distribution package version'), and the schema documents pagination parameters. It could be slightly more complete by stating that the response is a paginated list or indicating the relationship to alternative_distribution_package_deltas__get, but overall it covers the core information for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides full coverage (100%) for all three parameters: id, limit, and next_url, each with descriptive text. The description itself adds no extra parameter semantic beyond what the schema already states. With schema coverage this high, the baseline of 3 is appropriate; the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List the deltas belonging to an alternative distribution package version.' It uses a specific verb 'List' and the resource 'deltas' scoped to a package version, which unambiguously distinguishes it from sibling tools like alternative_distribution_package_deltas__get (which retrieves a single delta) and alternative_distribution_package_versions__variants__list (which lists variants, not deltas).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (to list deltas for a given alternative distribution package version) but does not explicitly state alternatives or exclusions. There is no mention of when a different tool would be more appropriate, such as alternative_distribution_package_deltas__get for fetching a single delta. The usage context is clear from the verb and resource, but no explicit guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the agent knows this is a destructive, retryable operation. The description adds only the endpoint path, which does not provide additional behavioral context like irreversibility or permission requirements. 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 extremely concise, consisting of one action statement and an endpoint reference. It is front-loaded and contains no unnecessary words, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema, strong annotations), the description is nearly complete. It clearly identifies the action and resource, and the schema fills in the parameter requirement. Minor gap: it does not explicitly state the deletion is permanent, but this is implied by destructiveHint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'id' parameter fully described as 'ID from the matching list call.' The tool description's URL template '{id}' adds no semantic value beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete an analytics report request' with a specific verb and resource. The HTTP DELETE endpoint reinforces the action, and it is unambiguous alongside sibling tools like analytics_report_requests__create and analytics_report_requests__get.
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 verb 'Delete' implies when to use, and the resource name identifies the target. However, there is no explicit guidance on when not to use it or any mention of alternatives, such as the need to obtain an ID from a list or create call first. The schema does provide this hint, but the tool description itself lacks direct usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the HTTP endpoint '[GET /v1/analyticsReportRequests/{id}]' which is useful but minimal; no further behavioral details like response shape or error handling are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence plus the endpoint path, with no wasted words. It is front-loaded with the primary action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with good annotations and full schema coverage, the description is mostly complete. It lacks an output schema or mention of return fields, but the optional include/fields parameters hint at response variability; still, the core selection and invocation needs are met.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter having a description. The description itself does not add parameter-level meaning beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one analytics report request by ID,' specifying the verb, resource, and scope (by ID). This distinguishes it from list operations like analytics_report_requests__reports__list or apps__analytics_report_requests__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?
Usage is implied for a simple get-by-ID operation, but the description does not explicitly state when to use this tool versus alternatives. The ID parameter's schema says 'ID from the matching list call,' which gives some context, but the description itself lacks explicit guidance or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds the parent-child relationship and endpoint but does not disclose additional behavioral traits like pagination behavior or return format. With annotations present, the description provides some value but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and includes the endpoint in brackets as a useful 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?
With annotations covering safety and schema covering all parameters, the description is sufficient for a simple list operation. It lacks an output schema and does not elaborate on what constitutes a 'report', but the context is adequate given the siblings and endpoint. Minor gaps prevent a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter has a meaningful description (e.g., 'ID from the matching list call', 'filter by attribute name'). The description adds no additional parameter semantics, so the baseline of 3 for high schema coverage is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'reports belonging to an analytics report request', which is specific and distinguishes it from siblings like analytics_report_requests__get (gets the request itself) and analytics_reports__get (gets a single report). The endpoint is also provided.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to list reports under a specific analytics report request) but does not explicitly mention alternatives or exclusion cases. The context is clear enough, but no explicit guidance is provided for choosing between this and similar list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the HTTP endpoint but no additional behavioral details like return format, pagination, or rate limits. With annotations present, a 3 is appropriate as it does not contradict and adds minimal 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 a single sentence with the key action and endpoint, zero waste. It is front-loaded and immediately comprehensible.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with complete schema coverage and safety annotations, the description is sufficient. The lack of an output schema is mitigated by the straightforward purpose, though a bit more detail on return values could enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters ('id' and 'fields_analyticsReports') have clear descriptions. The tool description itself adds no extra semantic value beyond the schema, so the baseline score 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?
The description clearly states 'Read one analytics report by ID' with a specific verb ('Read'), resource ('analytics report'), and scope ('by ID'). This distinguishes it from sibling list tools like analytics_reports__instances__list. The endpoint reference adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'by ID' but does not explicitly state when to use this vs alternatives. It lacks guidance on when not to use it (e.g., when needing multiple reports) or mention of related list/get siblings. The prerequisite of having an ID from a list call is only in the schema, not the description.
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 false. The description simply says 'Read,' which is consistent but adds no additional behavioral context like return size, pagination, or permission requirements. The size warning appears in the schema parameter description, not the tool description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource, and includes the HTTP endpoint for clarity. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With readOnly/idempotent annotations and a fully described schema, the tool is adequately specified for a simple get-by-ID operation. The description is minimal but sufficient, and the ID parameter's reference to the list call helps complete the context. No output schema is present, but none is needed for a read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters clearly described: id as 'ID from the matching list call' and fields as selectable attributes with a note about the 200 KB row size. The tool description itself adds no parameter meaning, relying fully on the schema, which meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Read one android to iOS app mapping detail by ID,' which clearly identifies the action (read) and resource (android-to-iOS mapping detail). This differentiates it from sibling tools like the create/update/delete variants and the list tool, which serve different purposes. The endpoint path reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage via 'by ID' but does not explicitly mention alternatives or when-not-to-use. The schema's id parameter description 'ID from the matching list call' provides some context, but the description itself lacks explicit guidance on choosing this tool over the list or other mapping 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, idempotentHint, and destructiveHint, so the agent knows this is a safe, idempotent read. The description aligns with those annotations by starting with 'Read,' but adds no extra behavioral context beyond the endpoint; this is acceptable for a simple GET but not a rich disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that states the operation, resource, and endpoint with no filler or redundant clauses. It is front-loaded with the actionable verb and resource, making it easy for an agent to scan quickly.
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-by-id tool, the description plus annotations and fully documented schema provide enough to select and invoke the tool. It lacks explicit error/not-found behavior or output details, but the absence of an output schema and the simplicity of a GET make this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the input schema already explains that id comes from a matching list call, that include is a comma-separated relationship list, and that fields limits the returned attributes. The description itself adds no parameter-level meaning, so it meets the baseline but does not compensate 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 opens with 'Read one app availabilities (v2) by ID,' which names a specific verb ('Read'), a specific resource ('app availabilities v2'), and a clear scope ('one ... by ID'). It also includes the REST endpoint, distinguishing it from sibling list/create tools like app_availabilities_v2__territory_availabilities__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 the tool is for fetching a single availability record when an ID is known, but it does not explicitly state when to use it instead of the related list or territory-availability tools. The schema notes that the ID comes from a matching list call, but that guidance is not in the description itself, leaving usage context implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, repeatable read. The description adds the relationship that localizations belong to a default experience, but does not disclose pagination or filtering behavior beyond what the schema parameters already show. 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 a single sentence with the endpoint path included, zero extra fluff. It front-loads the verb and resource, making it highly scannable and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with complete annotations and full schema documentation, the description sufficiently orients the agent. It lacks an explicit note about response shape or pagination, but the 'limit' and 'fields' parameters are documented in the schema. Overall adequate for a well-structured tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all six parameters including their types and purpose. The description adds no additional parameter semantics beyond echoing the id in the endpoint path, which is already in the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'List' with a clear resource ('App Clip default experience localizations') and scoping parent ('an App Clip default experience'), distinguishing it from sibling tools that get, create, update, or delete localizations. The endpoint path reinforces the resource hierarchy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but does not explicitly say when to use it versus related tools like app_clip_default_experience_localizations__get (single fetch) or the create/delete variants. The context implies listing all localizations for a given default experience, but no explicit alternatives or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description's 'Read' aligns with these hints but adds no additional behavioral context such as pagination, rate limits, or error conditions. With annotations present, this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, leading with the action and resource, followed by the endpoint. Every word earns its place, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with read-only annotations and a well-described schema, the description is adequate. It doesn't describe return values, but the resource name and endpoint make it clear. It omits any caveats, but given the tool's simplicity, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with descriptions for all three parameters (id, include, fields_appClipDefaultExperiences), so the description does not need to explain them. The description itself adds no parameter-level details, but the schema already handles 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 'Read one App Clip default experience by ID' with a specific verb and resource, distinguishing it from sibling tools that create, update, delete, or list. The HTTP endpoint reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single App Clip default experience by ID, but it does not explicitly state when to use this tool versus alternatives (e.g., list endpoints) or any prerequisites beyond the ID. No exclusions or alternative tools mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description's 'Read' aligns with these annotations and adds the HTTP GET endpoint, but it provides no additional behavioral context such as return format or relationship handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately conveys the purpose and includes the endpoint. There is no redundant or unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation, the description covers the core purpose, and the schema fills in parameter details. Annotations cover safety. However, it could clarify what is returned or how include/fields affect the response, so slightly above baseline.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters having descriptions in the schema. The description itself does not elaborate on parameters, so it adds no extra meaning beyond the schema; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads one App Clip by ID, using a specific verb and resource. The GET endpoint confirms the operation, and it distinguishes this tool from list operations and related resource gets in the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives, such as listing App Clips or retrieving related resources. Usage is implied by the action 'Read one App Clip by ID', but no alternative tools or exclusions 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 idempotentHint=true, which the description aligns with by using 'Read'. The description adds only the endpoint path, without additional behavioral context such as error handling or response 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 a single sentence, front-loaded with the action, and includes the endpoint. No extraneous 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 strong annotations and complete schema coverage, the description provides adequate context for invoking the tool. However, it does not describe the return value structure, which is left to the schema's fields parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents both parameters; the id parameter includes the explanation that it comes from the matching list call, and the fields parameter lists all enum values. The description adds no parameter information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' with a clear resource ('one app encryption declaration document') and scope ('by ID'). This distinguishes it from sibling create and update tools for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. The purpose is implied (fetch a single document), but no alternatives or exclusions are mentioned, making it adequate 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 provide readOnlyHint, idempotentHint, and destructiveHint, so the agent knows it is a safe read. The description adds the HTTP endpoint path, which is useful context, but does not disclose additional behavioral details such as response format, download type, or any special handling. 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 a single concise sentence followed by the HTTP path. Every word earns its place, and the purpose is front-loaded. No unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter GET operation with strong annotations, the description is nearly complete. It clearly identifies the resource and operation. However, it does not describe the return value (e.g., whether it's a binary document download), which could be relevant for an agent handling the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single 'id' parameter ('ID from the matching list call'), which already explains its meaning. The description does not add extra parameter semantics beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation (read) and the resource (app encryption declaration document) with the scope 'for an app encryption declaration'. The HTTP path reinforces this, and the phrasing distinguishes it from siblings like app_encryption_declarations__get (which returns the declaration itself) and app_encryption_declaration_documents__get (which likely fetches by document ID).
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 use case is implied: you have an app encryption declaration ID and want its document. However, there is no explicit guidance on when to choose this tool over related alternatives like app_encryption_declaration_documents__get, and 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, idempotentHint=true, and destructiveHint=false. The description adds the endpoint (GET /v1/appInfos/{id}) and the 'Read' verb, which align with the annotations but do not disclose additional behavioral aspects such as authentication requirements, rate limits, or error conditions. It is consistent with annotations, so 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 concise sentence, front-loaded with the key action, followed by the endpoint. It contains no unnecessary wording and communicates the essential purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with good annotations and full schema parameter descriptions, the description is adequate. It omits return value details, but no output schema exists and the tool's scope is narrow. The endpoint adds context, and the schema already clarifies relationship inclusion. Minor gap: no mention of when to use include/fields, but those are explained in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed descriptions for id, include, and fields_appInfos. The description itself does not add parameter details but reinforces the 'by ID' concept. Baseline of 3 is appropriate since the schema already covers parameter meaning effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one app info by ID', which specifies the action (read), the resource (app info), and the method (by ID). This distinguishes it from write operations like app_infos__update and from relationship-specific reads like app_infos__primary_category__get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single app info by ID, and the schema hints at obtaining the ID from a list call. However, it does not explicitly state when to prefer this over alternatives like apps__app_infos__list, nor does it provide exclusions or prerequisites. The guidance is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with the readOnlyHint and idempotentHint annotations by stating 'Read', and adds the endpoint URL. However, it does not disclose additional behavioral details such as error handling, pagination, or authentication, which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, consisting of one sentence plus the endpoint reference. It is front-loaded and contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET endpoint with one required parameter, the description, combined with schema and annotations, provides sufficient context. However, it does not describe the return payload or any related behavior, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters (id and include) with descriptions. The tool description adds no parameter-level detail, so the schema carries all the meaningful information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('secondary subcategory one for an app info'), and includes the endpoint URL. It distinguishes this tool from sibling tools like app_infos__primary_subcategory_one__get and app_infos__secondary_subcategory_two__get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It implies usage when you need the secondary subcategory one, but does not mention exclusions or alternative tools, so the guidance is minimal.
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, so safety is covered. The description adds the HTTP endpoint but no additional behavioral context (e.g., what happens if the app info doesn't exist, auth requirements, or relationship semantics). This is adequate but does not go beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence plus the endpoint path. Every word earns its place, with no fluff or repetition. It is front-loaded and immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter with full schema coverage and strong annotations, the description is nearly complete. It lacks a brief note on the relationship between secondary subcategory two and other subcategories, but the endpoint and resource name provide sufficient context. No output schema is present, but the tool's simplicity mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both 'id' and 'include' parameters. The description itself adds no parameter-level detail, which is acceptable given the schema's thoroughness. 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 'Read the secondary subcategory two for an app info' with a specific verb and resource, and the endpoint path adds precision. It distinguishes from siblings like secondary_subcategory_one and primary subcategory tools by explicitly naming 'secondary subcategory two'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need the secondary subcategory two for an app info) but gives no explicit guidance on when to choose this over sibling subcategory getters or exclusions. The endpoint and resource name make the context clear, but no alternatives or when-not-to-use 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 idempotentHint=true, so the safe read-only nature is covered. The description adds little beyond the endpoint and basic listing behavior, which is acceptable given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence followed by the endpoint. Every word earns its place, and the core action is front-loaded. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET list operation, the description plus fully documented schema and safety annotations are sufficient. The schema covers pagination, includes, fields, and filters, so the description need not repeat those details. A minor gap is the absence of any mention of the response format, but this is not critical for a straightforward 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 description coverage is 100%, so the input schema already documents all six parameters thoroughly. The description adds no parameter-level detail beyond referencing the app id in the endpoint, matching 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 states a specific verb and resource: "List the App Clips belonging to an app." It clearly distinguishes this from sibling tools like app_clips__app_clip_default_experiences__list and app_clips__app_clip_advanced_experiences__list, and the endpoint path reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when you need the App Clips for a given app. However, it does not explicitly mention alternatives or identify when not to use it, so the usage guidance is only implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the 'List' wording is consistent with that. The description adds the endpoint but does not disclose additional behavioral details such as pagination behavior or response shape. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence followed by the endpoint reference. It is front-loaded with the action and scope, and every part is useful with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation, the description plus complete schema and safety annotations is nearly sufficient. It does not describe the returned list structure or explicitly differentiate from the unapp-scoped sibling, but the endpoint and required app id give enough information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 7 parameters thoroughly. The endpoint line does clarify that id is a path parameter, but the description otherwise adds no meaningful parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('app encryption declarations'), and the scope ('belonging to an app'), plus the exact endpoint. This distinguishes it from the sibling app_encryption_declarations__list, which appears to be the non-app-scoped equivalent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the core use case clear: call when you need encryption declarations for a specific app, identified by the app id in the path. However, it does not explicitly name any alternative tool or describe when not to use it, so selection among sibling list tools is left mostly to 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, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the explicit GET endpoint, which reinforces read-only semantics, but provides no further behavioral context such as pagination behavior or API-specific quirks.
Agents need to know what a tool does to the world before 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 one focused sentence plus the endpoint. It is front-loaded with the action and resource, and every element adds value without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with full schema coverage and rich annotations, the description is nearly complete. It identifies the resource, the endpoint, and the scope. A brief note on when to use this instead of the app-store-version-scoped sibling would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all five parameters. The description does not add parameter-level detail, but it does not need to compensate for missing schema information. 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 states a specific verb ('List'), a specific resource ('App Store version experiments (v2)'), and the owning entity ('belonging to an app'), plus the exact endpoint. This clearly distinguishes it from sibling tools like app_store_version_experiments_v2__get and app_store_versions__app_store_version_experiments_v2__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 the use case: retrieving v2 experiments for an app, with the endpoint reinforcing that scope. However, it does not explicitly state when to prefer this over similar sibling tools, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the 'List' semantics match that profile with no contradiction. The description adds the review-state context but does not disclose pagination behavior (despite limit/next_url in the schema), auth requirements, or what happens for invalid app IDs, so it adds only modest value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler: action, resource, distinguishing output, then endpoint reference. The core behavior is front-loaded and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool whose safety profile is fully covered by annotations and whose 10 parameters are 100% documented in the schema, the description is nearly sufficient. The main gap is behavioral context such as pagination defaults or the cost implications of the include parameter, though schema documentation partially mitigates these; an explicit note about pagination would make it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds slight value by exemplifying filter values (PREPARE_FOR_SUBMISSION, WAITING_FOR_REVIEW, READY_FOR_SALE) that correspond to filter_appStoreState/filter_appVersionState, but the schema already documents all parameter meanings including the id flexibility (name, bundle ID, or Apple ID).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('List') with a clear resource ('App Store versions') scoped to an app via the endpoint path [GET /v1/apps/{id}/appStoreVersions]. The review-state detail (PREPARE_FOR_SUBMISSION, WAITING_FOR_REVIEW, READY_FOR_SALE) adds a distinguishing output feature that separates it from single-resource siblings like app_store_versions__get or mutation tools like app_store_versions__create.
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 'List' verb and collection endpoint imply this is for enumerating versions rather than fetching one or mutating one, but no explicit when-to-use guidance or alternative routing is provided. An agent must infer usage from the verb and endpoint rather than being told when to prefer this over siblings like app_store_versions__get or apps__builds__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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the GET endpoint confirmation and the app-scoping constraint, which is useful but minimal; it does not discuss pagination, response size, or filtering behavior. With strong annotations, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence states verb, resource, and scope, with the endpoint path appended as a compact reference. Every word earns its place and nothing is redundant with the schema or annotations.
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 operation with 13 parameters, the schema carries the full parameter burden and the annotations carry the full safety burden, so the description only needs to orient the agent on resource and scope, which it does. It could optionally note the relationship to the screenshot-submissions sibling, but nothing essential to invoking the tool correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 13 parameters individually documented (including behavioral notes like the empty-list-on-no-match filter behavior and the include relationship cost). The description itself adds no parameter-level meaning beyond echoing the endpoint's {id} placeholder, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (List), resource (beta feedback crash submissions), and scope (belonging to an app), which unambiguously identifies what the tool does. This clearly distinguishes it from siblings like beta_feedback_crash_submissions__get/delete (single-resource operations) and apps__beta_feedback_screenshot_submissions__list (a different submission type) without needing to open the schema.
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 scope 'belonging to an app' implies the use case: retrieving all crash submissions for one app, keyed by the required id. However, the description offers no explicit when-to-use guidance, exclusions, or named alternatives, even though the near-identical sibling apps__beta_feedback_screenshot_submissions__list exists and could easily be confused with this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the read-only nature is covered. The description adds the app-scoping and endpoint context but does not disclose additional behavioral details such as pagination behavior or response characteristics, which is acceptable but not additive beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that names the operation and resource, followed by a compact endpoint reference. There is no wasted wording, and the information is immediately useful.
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?
Although the tool has 13 parameters and no output schema, the schema descriptions are thorough and the list semantics make the return shape inferable. The description provides the key operation and scope; only a brief note about pagination or expected response would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, including rich details on the app id, filters, sort, and field selection. The description adds only the implied path parameter {id} from the endpoint, so it does not meaningfully improve on the schema's parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a specific resource ('beta feedback screenshot submissions') scoped to an app, and includes the exact GET endpoint. This clearly distinguishes it from siblings like the singular getter and deleter for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is clear from the wording: use this to list the screenshot submissions for an app. However, it gives no explicit guidance on when to prefer this over alternatives such as beta_feedback_screenshot_submissions__get or apps__beta_feedback_crash_submissions__list, leaving that to 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, and destructiveHint=false, fully covering the safety profile. The description adds the GET endpoint, which confirms the read-only nature, but discloses no additional behavioral traits such as pagination behavior, default page size, or response structure. With annotations carrying the safety burden, this is adequate but not additive.
Agents need to know what a tool does to the world before 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 sentence plus endpoint reference with zero wasted words. The verb and resource are front-loaded, and the endpoint provides precise API grounding. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation, the combination of description, schema (100% parameter coverage), and annotations (safe, idempotent) covers the essentials: purpose, required id param, pagination controls, and field selection. The description does not explicitly address pagination sequencing, but the schema's limit and next_url parameters imply it, making the package sufficient for an agent to call this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the four parameters (id, limit, next_url, fields_betaGroups) already well-documented in the schema, including the id format options and the 200 KB row-set warning. The tool description itself adds no parameter-level meaning beyond the {id} placeholder in the endpoint, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List the beta groups belonging to an app,' with clear scope (app-scoped rather than global). The endpoint [GET /v1/apps/{id}/betaGroups] reinforces the resource and differentiates it from siblings like beta_groups__list and beta_groups__get, which operate at different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'belonging to an app' implies the use case — you need beta groups for one specific app identified by the id parameter. However, it never explicitly names alternatives or states when NOT to use it versus beta_groups__list (global listing) or beta_groups__get (single record). The usage context is clear but the exclusion logic is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate read-only and idempotent behavior. The description adds a useful detail about sort ordering ('newest first when sorted by -uploadedDate'), but does not disclose pagination behavior or other response characteristics. With annotations covering safety, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact sentence conveys the core action and scope, followed by the endpoint reference. No filler or redundancy. The most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description combined with full schema coverage and safety annotations is mostly complete. Pagination behavior is left implicit via the limit and next_url parameters, but this is a minor gap given the schema descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all four parameters. The description does not need to repeat parameter details. It adds a small hint about uploadedDate ordering, but the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource: 'List builds uploaded for an app.' It also clarifies the resource scope ('for an app'), which distinguishes it from broader endpoints like builds__list. The endpoint reference adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you need builds belonging to a specific app, but it does not explicitly contrast it with alternatives such as builds__list or builds__get. There is no 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds only the app-scoping constraint and the GET method, but does not reveal behavioral details such as pagination cost, relationship-fetching implications, or response shape beyond what the schema and annotations already imply.
Agents need to know what a tool does to the world before 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, front-loaded sentence that directly states the action, resource, scope, and endpoint. There is no filler, repetition, or unnecessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, read-only list operation with full parameter documentation and safety annotations, the description is mostly sufficient. It clearly identifies the scope and operation; the main gap is that there is no output schema and the description does not describe the return shape, though that is partially inferable from the list semantics and the field-selection parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema itself documents all five parameters with meaningful detail, including pagination, relationships, and field selection. The tool description adds no parameter-level meaning of its own, so the 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?
The description uses a specific verb ('List') plus a precise resource ('promoted purchases') and an app-scoping qualifier ('belonging to an app'). It also includes the exact GET endpoint, making the operation unambiguous and distinguishing it from the sibling mutation tool apps__promoted_purchases__replace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied by the verb 'List' and the endpoint pattern, but the description gives no explicit guidance about when to choose this tool over alternatives, such as when a caller needs to modify promoted purchases rather than read them. There is no 'use this when...' or exclusionary note.
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 description adds no behavioral context beyond what the annotations already provide. Annotations indicate destructiveHint=true, readOnlyHint=false, and idempotentHint=true, and the description merely repeats the delete action without mentioning side effects, permanence, or any special conditions. No contradiction exists, but no additional value is added.
Agents need to know what a tool does to the world before 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 plus the endpoint reference. Every word is relevant, and there is no redundancy or unnecessary detail. It is efficiently front-loaded with the main action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and no output schema, the description is complete enough. It specifies the resource and the HTTP method, and the schema provides the needed parameter. While it does not explain the return value or prerequisites, those are standard for a delete endpoint and not strictly required given the annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of the parameters, with the 'id' field described as 'ID from the matching list call.' The tool description itself does not elaborate on the parameter, but the schema already provides sufficient meaning. This matches the baseline of 3 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 the action: 'Delete an App Store review attachment.' This uses a specific verb and resource, and the included endpoint [DELETE /v1/appStoreReviewAttachments/{id}] further confirms the purpose. It unambiguously distinguishes this from sibling tools like create, update, or 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 clearly implies the tool is for deleting App Store review attachments, and the verb 'Delete' provides the context of when to use it. However, it does not explicitly mention alternatives or exclusions, such as 'use update to modify an existing attachment' or 'this cannot be undone.' The context is clear enough given the tool's name, so a 4 is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds the parent-child relationship scope but does not disclose additional behavioral details such as pagination behavior, response format, or authentication requirements. Since annotations cover safety, the minimal added context is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by the endpoint specification. It is extremely 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with robust annotations and a fully self-describing schema, the description is adequate. It identifies the resource, parent, and endpoint. It does not explain the return structure, but given the resource name and field list in the schema, the response shape is inferable. No explicit guidance on pagination or edge cases is needed for this simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, with each parameter (id, limit, include, next_url, fields_appStoreReviewAttachments) already described. The description itself does not add any parameter-specific information, so it stays at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'List' and identifies the exact resource ('App Store review attachments') and its parent scope ('belonging to an App Store review detail'). The endpoint is also provided for verification. This clearly differentiates it from sibling tools like app_store_review_attachments__get, which likely retrieves a single attachment.
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 you would use this tool to list attachments for a given review detail, but it does not explicitly state when to use it over alternatives. No exclusions or references to sibling tools are provided, though the intended context is fairly obvious from the title and endpoint.
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=false, covering the safety profile. The description adds the parent-child relationship and the exact endpoint but does not disclose pagination behavior or response shape beyond that. 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 a single sentence followed by the endpoint path. It is front-loaded with the action and resource, with no extraneous words or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with strong annotations and a fully documented schema, the description is sufficient. It clearly identifies the resource and endpoint, though it does not describe the response format beyond 'List', which would be helpful given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, limit, include, next_url, fields) adequately documented in the schema. The description itself adds no parameter-specific information, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (List) and the resource (App Store version experiment treatments) with a scoping relationship ('belonging to an App Store version experiments (v2)'). The endpoint path reinforces the exact operation. This distinguishes it from sibling tools that get, create, or update individual treatments.
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 use case (listing treatments for a specific experiment) but does not explicitly contrast with alternatives such as app_store_version_experiment_treatments__get or list operations for other resource types. There is no when-not-to-use guidance, yet the action and resource make the intended context clear.
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 the tool as read-only, idempotent, and non-destructive. The description adds the endpoint and confirms the read nature, but does not disclose additional behavioral details such as error handling, authorization requirements, or default response size. It is consistent with the annotations, so 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, front-loaded sentence that states the action, resource, and scope, followed by the endpoint. There is no redundancy, filler, or unnecessary detail—every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with strong annotations and complete schema descriptions, the description is adequate. It could explicitly state what is returned (e.g., the treatment object and optional relationships) or mention the include parameter, but the schema already covers that. Overall, it is nearly complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (id, include, fields_appStoreVersionExperimentTreatments). The description itself only repeats 'by ID' and does not add meaning beyond the schema. Since the schema fully documents parameter semantics, the baseline score 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?
The description clearly states the action ('Read'), the target resource ('App Store version experiment treatment'), and the scope ('by ID'), distinguishing it from list/create/update/delete siblings in the tool set. It also includes the exact REST endpoint for additional disambiguation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific ID and need a single treatment, but it does not explicitly mention alternatives like listing all treatments or when to use create/update/delete. No exclusionary guidance is provided, leaving the agent to infer usage from the verb and resource.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds the nuance that this is an 'unlink' operation (relationship removal) rather than a hard delete of keyword objects, which is useful context. However, it does not disclose additional behaviors like partial failures, permissions, or the fate of the keyword resources.
Agents need to know what a tool does to the world before 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 sentence followed by the endpoint. Every word earns its place, and the most important action verb is front-loaded. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple semantics, the 100% schema coverage, and the annotations, the description is adequate. It clearly names the action and target resource. It does not explicitly instruct the agent to provide keyword IDs in the body, but the schema makes that obvious. No output schema is present, so the description doesn't need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%: the id is described as 'ID from the matching list call' and the body is fully structured as a JSON:API linkage request. The description adds no additional parameter meaning beyond the endpoint's {id} placeholder, so it does not improve on the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource pattern: 'Unlink search keywords from an App Store version localization.' It clearly distinguishes this from the sibling add/list tools by stating the unlink action and the exact DELETE 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?
The description implies when to use this tool (when you want to unlink search keywords), but it does not explicitly mention alternatives or contrast with the add/list sibling tools. The DELETE endpoint makes the use case clear, but there is no direct when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'Read' is consistent with these. The description adds the endpoint and resource context but does not disclose additional behavioral traits such as error handling, response format, or rate limits. This is adequate given the annotation coverage but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence followed by the endpoint, with no unnecessary words. It is front-loaded with the action and resource, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with two well-described parameters and read-only annotations, the description is nearly sufficient. However, it does not mention the response structure (no output schema exists) and lacks direct comparison to sibling tools, which would improve completeness. The resource is still unambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with meaningful descriptions for both parameters (id and include). The tool description itself does not add any parameter semantics beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read'), the resource ('alternative distribution package'), and the parent context ('App Store version'). The endpoint URL further reinforces the precise scope, distinguishing it from sibling tools that retrieve packages directly or from other related resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for reading a package associated with a specific App Store version, which is clear context. However, it does not explicitly compare it to sibling tools like alternative_distribution_packages__get or provide exclusion criteria for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, and the description consistently says 'Read', so no contradiction. But the description adds little behavioral context beyond what the annotations provide, such as error cases or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus the endpoint, with no waste. Front-loads the action and resource.
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?
This is a straightforward read operation with good annotation coverage and a clear endpoint. The description is sufficient for understanding the tool's role, though it doesn't elaborate on return structure or related data inclusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to explain parameters. The endpoint shows {id} but the schema already documents id and include.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action ('Read') and resource ('App Clip default experience') with a parent scope ('for an App Store version'). It distinguishes the tool from siblings like app_clip_default_experiences__get by scoping it to a specific app store version relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving the default App Clip experience associated with a given App Store version, and the endpoint reinforces this. However, it does not explicitly compare to sibling tools or state conditions for using this over the generic app_clip_default_experiences__get.
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, and destructiveHint=false, and the description's 'Read' and GET endpoint align with them. The description adds little behavioral detail beyond the resource scope (e.g., no pagination, error, or relationship behavior), but for a simple read-only GET this is acceptable; no annotation contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One concise sentence plus the endpoint reference; no filler. The main information appears first and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only detail GET with full schema coverage and safety annotations, the description is nearly sufficient. It could add one sentence on choosing this endpoint over the standalone review-detail endpoint, but the combination of title, path, schema, and sibling names supplies most needed context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline applies. The id parameter's purpose and the include relationship behavior are already described in the input schema; the description adds no additional parameter meaning beyond identifying the App Store version context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and names the exact resource ('App Store review detail for an App Store version') with the endpoint path included. The 'for an App Store version' qualifier distinguishes it from the standalone app_store_review_details__get 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 the tool is for reading a review detail scoped to an App Store version, but it does not explicitly state when to choose this over app_store_review_details__get or provide exclusions/alternatives. The include parameter hint in the schema gives some usage context but not tool-selection guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds the GET endpoint but no additional behavioral context such as error behavior or rate limits. With annotations covering the core traits, this is adequate but not enriched.
Agents need to know what a tool does to the world before 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 one concise sentence plus the endpoint, with zero filler. It immediately states the verb and resource, making it highly scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-resource GET with full schema coverage and strong annotations, this is essentially complete. It lacks explicit mention of response shape, but the fields parameter enumerates available attributes, and the endpoint convention implies a standard resource object. The tool is slightly less rich than the 'get_calls' exemplar, hence 4 rather than 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with id, include, and fields_appStoreVersions all thoroughly described. The description adds no parameter-specific meaning; as expected, the schema carries the load. This meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies the resource as 'one App Store version by ID', clearly distinguishing this singular get operation from sibling operations like deletion or list endpoints. The endpoint reference reinforces the exact resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when you have a specific version ID to retrieve, but it doesn't explicitly mention when to prefer it over alternatives such as listing versions. The id parameter schema hints that the ID comes from a 'matching list call', but no explicit when/when-not guidance is given in the description itself.
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, and destructiveHint=false. The description adds the GET endpoint and the app-scoping detail, both consistent with the annotations. It does not, however, disclose pagination behavior, response format, or any other non-obvious operational traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence followed by the endpoint. It is front-loaded with the core action and object, contains zero filler, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation, the description combined with the fully documented schema and the safety annotations is largely sufficient. It could add pagination or response-detail context, but the tool's simplicity and the schema coverage make the missing pieces non-critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents all 5 parameters (id, limit, include, next_url, fields_webhooks). The description adds no additional parameter context, which is acceptable given that the schema already carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List'), a specific resource ('webhooks'), and a scoping relationship ('belonging to an app'). The HTTP endpoint [GET /v1/apps/{id}/webhooks] reinforces the exact resource and distinguishes it from the many sibling list tools for other app subresources.
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 by noting the webhooks belong to an app, but it does not explicitly state when to use this over alternatives or mention any exclusions. There is no reference to sibling tools, leaving the agent to infer the intended use from the name and endpoint 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is known. The description adds the GET endpoint path but does not disclose additional behavioral traits such as pagination behavior or default limits. With annotations covering the main safety aspects, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that includes the operation and endpoint path. It contains no filler or redundant information, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with solid annotations and full schema coverage, the description is fairly complete. It identifies the resource and operation but does not describe the response structure; however, no output schema exists and the purpose is simple. The lack of explicit alternatives or additional behavioral context prevents a score of 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for id, limit, next_url, and fields_territories. The description does not add any parameter-specific meaning beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation: 'List the territories belonging to an app tag.' The verb 'List' and the resource 'territories belonging to an app tag' are specific. The endpoint path adds precision and distinguishes it from siblings like apps__app_tags__list (lists app tags) and territories__list (lists all territories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving territories for a specific app tag, but it does not explicitly state when to use this tool versus alternatives (e.g., territories__list for all territories). No exclusions or alternative guidance is provided, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds a useful behavioral disclosure beyond that: it makes a single lightweight API request to Apple to verify credentials. Optional flags' extra network calls are documented in the schema parameter descriptions, and all behavior remains read-only. It could mention more about side effects or cost, but this is well covered for a read-only status tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no filler. The first sentence front-loads the core reporting scope, and the second adds the credential verification behavior. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only status tool with a fully self-documenting schema, the description is nearly complete. It states what is reported, that one API call is made, and optional probes are explained in the parameters. There is no output schema, so the description could more explicitly describe the response shape, but the listed report items provide enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The parameter descriptions in the schema fully cover defaults, number of extra API calls, and usage guidance. The main tool description adds no parameter-level meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Report') and lists exactly what is reported: server configuration, spec version, loaded domains, JWT token state, and remaining API rate limit. It also adds the credential verification behavior. However, it does not explicitly differentiate itself from sibling tools like asc__account_status or asc__discover_domains.
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 implies it is a status/health check and 'verifies credentials' suggests when it might be used, but there is no explicit statement of when to use this tool versus alternatives or when not to use it. The check_capabilities parameter description contains embedded usage guidance, but the main description does not.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly=false, idempotent=true, and destructive=false, and the description aligns with these. The description adds the PATCH method indicating partial update semantics, but does not elaborate on failure modes, permissions, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence paired with the endpoint reference. Every word serves a purpose with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple update operation, rich schema, and annotations, the description and schema together cover the essentials. It does not state the return value or explicitly describe partial update semantics, but the PATCH endpoint and schema's single attribute imply these. A small gap remains around expected response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage for both 'id' (existing invocation ID) and 'body' (JSON:API request body) with detailed nested structure. The description adds no additional parameter-specific meaning, so the schema carries the load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Update') and the resource ('beta App Clip invocation'), and includes the HTTP method and path. This unambiguously distinguishes it from sibling tools like create, delete, or get.
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 via 'Update' and the PATCH endpoint, but it does not explicitly state when to prefer this over other operations or mention any prerequisites/alternatives. No exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only the HTTP GET endpoint, which is consistent but adds no extra behavioral context such as error handling, rate limits, or side effects. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence stating the action and resource, followed by the endpoint. It contains no filler, repetitive wording, or structural issues, earning every word.
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-by-ID tool with rich annotations and a well-described schema, the description is complete enough. It clearly identifies the resource and operation, and the schema fills in details about parameters and return data. The absence of an output schema is somewhat mitigated by the 'fields_betaAppLocalizations' parameter description, which hints at the response structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with meaningful descriptions for each parameter (e.g., 'id' explains it comes from a list call, 'include' explains relationship costs, 'fields_betaAppLocalizations' explains sparse fields and size limits). The description itself does not elaborate on parameters, but the schema fully compensates, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Read'), resource ('beta app localization'), and scope ('one ... by ID'). This distinguishes it from the sibling beta_app_localizations__list, which retrieves multiple localizations, and makes the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys the core usage scenario (fetch a single record by ID) but does not explicitly mention alternatives like the list tool, nor provide exclusion criteria. The required 'id' parameter's description ('ID from the matching list call') offers implicit guidance, but the main description itself gives no direct comparison 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, idempotentHint, and destructiveHint false, so the description does not need to restate that this is a safe read. It adds the HTTP method and endpoint, but does not describe return format or any other behavioral traits. This adds some value beyond annotations but lacks rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and resource, with the endpoint in brackets. There is no wasted wording, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only relationship retrieval with one parameter and no output schema, the description is largely complete. It clearly identifies the resource and includes the endpoint, and the parameter description provides necessary usage context. However, it does not explicitly mention what the response contains (e.g., an App object), which would make it slightly more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter is fully described in the schema ('ID from the matching list call'), covering 100% of parameter semantics. The main description does not add any additional meaning about parameters, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('the app') in the context of 'a beta app review detail', distinguishing it from sibling tools that fetch the review detail itself or other related resources. The included HTTP path further confirms the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need the app for a given beta app review detail, but it does not explicitly state when to use this tool versus alternatives like apps__beta_app_review_detail__get. The parameter description hints at a prerequisite (ID from a list call), but this is in the schema, not the main description.
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, and destructiveHint=false, and the description's 'Read' is consistent. No additional behavioral context (e.g., response size, permissions, or relationship to list calls) is provided beyond what annotations and schema already cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus an endpoint path, with no redundant or filler content. It is front-loaded and direct.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only GET with well-documented parameters and safety annotations, the description is adequate and complete enough for an agent to invoke it correctly. It could mention the return format or the list relationship, but the resource name and ID parameter make the operation clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with useful descriptions for both parameters, including the 'ID from the matching list call' and the fields selection with a 200 KB warning. The description itself adds no parameter meaning beyond repeating 'by ID', so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read'), identifies the exact resource ('one beta crash log'), and specifies the lookup key ('by ID'). This clearly distinguishes it from list-style sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'by ID' phrasing implies use when a specific crash log identifier is known, but there is no explicit when-to-use guidance or mention of alternatives such as list calls. The schema's id description hints at 'matching list call', but the main description provides no usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds the resource type and endpoint but no further behavioral context such as response format, authentication needs, or pagination, which is a minimal contribution 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 a single concise sentence plus an explicit endpoint string. Every word is purposeful, and the key action and resource are front-loaded with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter GET operation with robust annotations, the description is adequate. It lacks an explicit statement about the return content or authentication context, but the endpoint and verb make the purpose clear. Given no output schema, a brief note on the response format would have made it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of the single 'id' parameter, including a helpful description ('ID from the matching list call'). The tool description itself does not add parameter semantics beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read the crash log for a beta feedback crash submission' with a specific verb and resource, and includes the HTTP endpoint. This distinguishes it from sibling tools like beta_feedback_crash_submissions__get (which fetches the submission itself) and beta_crash_logs__get (which targets a different log context).
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 via the endpoint and the schema param note 'ID from the matching list call' indicates a prerequisite. However, it does not explicitly mention when to use this tool versus alternatives or when not to use it, leaving the agent to infer exclusions from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 covered. The description adds no extra behavioral context such as error cases, authentication, or rate limits. It doesn't contradict the annotations, but it doesn't enrich them either.
Agents need to know what a tool does to the world before 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 plus the HTTP endpoint. It is extremely concise, front-loaded with the action, and contains no filler. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple read-by-ID operation with well-documented parameters, the description is mostly complete. However, it does not explain the response structure or default fields, but the schema covers the include/fields modifiers. A small gap, but adequate for a straightforward GET.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all three parameters (id, include, fields_betaFeedbackCrashSubmissions). The description itself adds no parameter-specific detail beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and clearly identifies the resource 'one beta feedback crash submission by ID'. This distinguishes it from list operations and other get tools, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an ID (from a list call) but does not explicitly state when to use this tool versus alternatives like the list or delete sibling tools. There are no exclusions or alternative suggestions, so it's basic but not misleading.
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, and destructiveHint=false, covering the safety profile. The description adds the endpoint and the action but no additional behavioral context such as what happens when no app exists or authentication requirements. This meets the baseline where annotations handle safety and the description adds minimal extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus an endpoint annotation, with no filler or repeated information. It is front-loaded with the core purpose and every word contributes to understanding.
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 relationship getter with one parameter and strong annotations, the description is nearly complete. It states what it reads and the parameter source, and the endpoint clarifies the API path. Missing a description of the return value, but with no output schema and a straightforward 'get app' semantic, this is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter, with the description 'ID from the matching list call' already explaining the source of the ID. The tool description itself adds no further parameter details, so the 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?
The description clearly states the action ('Read') and the specific resource ('the app for a beta group'), making it distinct from sibling relationship getters like builds__app__get or beta_groups__get. The endpoint '/v1/betaGroups/{id}/app' further reinforces the exact REST operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage—if you need the app associated with a beta group, use this tool—but does not explicitly contrast with alternatives like beta_groups__get (which retrieves the group itself) or builds__app__get. No exclusions or alternative recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description does not need to restate these. It adds the endpoint and clarifies the resource scope, but provides no additional behavioral context such as auth requirements, response format, or potential side effects. Since there is no contradiction with annotations, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and resource, then provides the endpoint. There is no redundant or filler content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a simple read-only operation with one well-described parameter, strong annotations, and no output schema, the description is adequate. It could mention what the response contains (e.g., build ID or status), but the name and endpoint imply the check's purpose. For a tool of this complexity, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with one parameter 'id' described as 'ID from the matching list call.' The description does not add further parameter details beyond confirming the resource context. Baseline of 3 is warranted because the schema carries the parameter semantics 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 the action ('Read'), the resource ('beta recruitment criterion compatible build check'), and the scope ('for a beta group'). It also includes the exact endpoint, making the purpose unmistakable and distinguishing it from sibling tools like beta_groups__beta_recruitment_criteria__get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need the compatible build check for a beta group, and the parameter description adds 'ID from the matching list call', which is a usage hint. However, it does not explicitly state when to use this over alternatives or provide any exclusions, so it falls short of clear comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is clear. The description adds no further behavioral details (e.g., pagination behavior or whether only active testers are returned), but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the endpoint token, front-loading the action and object. There is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple read-only list tool with good annotations and fully described parameters; the description adequately communicates the scope. It lacks explicit return-format or pagination prose, but the schema documents limit/next_url and the endpoint implies a standard list response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: id, limit, next_url, and fields_betaTesters are all documented in the input schema. The description adds no additional parameter meaning, but the schema already carries that burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and identifies both the resource ('beta testers') and the scope ('belonging to a beta group'), clearly distinguishing it from broader tools like beta_testers__list. The endpoint pattern reinforces the relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need the testers for a specific beta group (requiring the id parameter), but it does not explicitly contrast with sibling tools such as beta_testers__list or builds__individual_testers__list. There is no 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 indicate the operation is not read-only, not idempotent, and not destructive. The description adds the behavioral outcome (testers can install the build) but does not disclose side effects, permissions, or reversibility beyond what annotations imply.
Agents need to know what a tool does to the world before 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 one clear sentence plus the endpoint reference. Every word contributes to understanding the tool's purpose and target resource.
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 relationship-add operation with detailed schema and annotations, the description is sufficient. It clearly states the purpose and effect, and the schema documents the required body structure. Lack of output schema is acceptable for a mutation with no return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the body parameter is well-defined by the JSON:API schema. The description adds minimal value by noting the id comes from 'the matching list call,' but does not elaborate on how to construct the body or source build IDs beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Distribute a build to a TestFlight beta group') with a clear outcome ('so its testers can install it'), and the endpoint is provided. This distinguishes it from removal operations like beta_groups__builds__remove.
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 use case of distributing builds to a group, but does not explicitly mention when to use it vs. alternatives such as builds__beta_groups__add or removal tools. It provides context but no explicit exclusions or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the GET endpoint and resource relationship but does not disclose pagination behavior or return details beyond what the schema suggests. 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 two concise sentences, including the endpoint reference. Every word earns its place; there is no wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with full annotation coverage and a complete schema, the description is adequate. It clearly states what is listed and includes the endpoint. However, it does not explicitly mention pagination behavior or return list structure, which would make it fully complete for an agent without external API knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-level meaning beyond the schema; it only restates the resource scope. The parameters (id, limit, next_url, fields_builds) are already well-documented in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ("List") and resource ("builds belonging to a beta group"), clearly distinguishing it from broader list tools like builds__list. The HTTP endpoint is also included, making the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for retrieving builds scoped to a specific beta group, but it does not explicitly mention when to use it over the sibling tools such as builds__list or beta_groups__builds__add/remove. No alternatives or exclusions are stated, so usage guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds valuable context by specifying that the response is aggregated time-series data rather than individual records, setting expectations for output granularity without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, starts with the main action, and includes the endpoint reference. Every sentence contributes meaning—purpose and output type—with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides sufficient context for a simple read-only metrics tool: it defines the resource, the kind of data returned (aggregated time-series), and the endpoint. Despite lacking an output schema, the characterization of the data as aggregated and time-series gives the agent a clear expectation. It could go deeper on units or date ranges, but this is adequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both 'id' and 'limit' are documented. The description itself adds no parameter details beyond what the schema provides, but since the schema is complete, a baseline of 3 is appropriate. Notably, the 'limit' schema description incorrectly says 'groups' instead of 'data points', but the tool description does not address this flaw.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'public link usages metrics for a beta group', and explicitly notes it returns aggregated time-series data, not individual records. It distinguishes itself from sibling metrics tools by naming the specific metric type and endpoint.
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 sibling metrics tools like beta_tester_usages__metrics or builds__beta_build_usages__metrics. There is no mention of exclusions, prerequisites, or alternative tools, leaving the agent to infer usage solely from the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds no further behavioral context beyond the verb 'Delete', such as irreversibility or side effects. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero unnecessary words. It includes the endpoint for extra precision while remaining minimal.
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 delete tool, the description plus annotations and schema are sufficient. The schema explains where the ID comes from, annotations cover the destructive nature, and no output schema is needed. Minor gap: no explicit mention of permanent deletion, but destructiveHint covers this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the one parameter 'id' already has a useful description. The tool description adds no additional parameter semantics; the baseline of 3 is appropriate since structured data carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' with the exact resource 'beta recruitment criteria' and includes the full endpoint. This clearly distinguishes it from other delete tools in the sibling 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 states what it does but does not provide explicit when-to-use or alternative guidance. The input schema's note 'ID from the matching list call' implies a prerequisite, but no explicit mention of alternatives or exclusions is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-idempotent, non-destructive mutation. The description simply says 'Link', which confirms a mutating add operation, but it does not clarify whether this appends to existing relationships or replaces them. With annotations covering the safety profile, the minimal description adds limited extra 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 a single sentence that states the action and includes the endpoint URL. Every word earns its place, with no redundant phrases.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two parameters, a detailed schema, and annotations. The description plus schema gives enough for the agent to invoke it, but it lacks explicit guidance on when to use this versus the inverse sibling tool. This minor gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema itself includes descriptions for both parameters (id as 'ID from the matching list call' and body as a JSON:API request). The description adds no additional parameter meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Link') and identifies both resources ('beta groups' and 'beta tester'), making the purpose unambiguous. The endpoint URL further clarifies the exact operation, and it is distinct from sibling tools like builds__beta_groups__add or beta_groups__beta_testers__add.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by stating the direction of the link (beta groups to a beta tester), but it does not explicitly contrast it with similar tools like beta_groups__beta_testers__add. No exclusions or alternative tool names are provided, leaving some ambiguity for an agent choosing between inverse relationship tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context beyond the read intent, such as pagination, response structure, or relationship inclusion. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the operation clearly and includes the API endpoint. It wastes no words and every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool, the description is sufficient given the rich schema and safety-focused annotations. It does not explain return value structure, but the schema clarifies the available include/field options. A small improvement would be mentioning that this returns a single beta tester resource or that it supports include for relationships, but this is not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter descriptions in the schema are already rich (e.g., 'ID from the matching list call', explanation of include, and note about row size for fields_betaTesters). The tool description adds no extra parameter semantics, so the 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?
The description clearly states 'Read one beta tester by ID' with a specific verb and resource, and the included HTTP path [GET /v1/betaTesters/{id}] further confirms the single-resource read operation. This distinguishes it from sibling tools like beta_testers__list (collection read) and beta_testers__delete (destructive).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied: use this when you have a beta tester ID and want to read that single resource. The schema's id parameter description ('ID from the matching list call') provides a subtle workflow hint, but the tool description itself does not explicitly mention when to use this vs. alternatives (e.g., saying 'for a list, use beta_testers__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?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read' is consistent with these. The description adds the endpoint but does not disclose error conditions or response format; however, the annotations provide sufficient safety 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 one concise sentence followed by the endpoint, with no filler or redundant information. Every element contributes to understanding the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read operation with strong annotations, the description provides sufficient context. The endpoint and name clarify the target resource, and the lack of an output schema is acceptable for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents the single parameter 'id' with 'ID from the matching list call', which is helpful and covers 100% of parameters. The tool description itself does not add parameter semantics, but none are needed given the schema's 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 'Read the app for a build' clearly states the action (read) and resource (app for a build). The endpoint [GET /v1/builds/{id}/app] reinforces the specific relationship, distinguishing it from sibling tools like builds__get which retrieve the build itself.
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 guidance is provided. However, the name and endpoint imply its purpose as the tool for fetching the app associated with a specific build, giving implied usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the description's 'Read' is consistent and adds no contradiction. It provides the endpoint but does not disclose additional behavioral traits such as auth requirements, error conditions, or return format. With annotations covering safety, this is adequate but not enriched.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb 'Read', immediately followed by the resource and endpoint. No redundant content; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with no output schema, the description identifies the return concept (App Store version) and the required input pattern (build ID). The include parameter description adds useful context about relationship fetching. It does not describe response structure, but the resource is standardized and inferable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, including the 'ID from the matching list call' note for id and a detailed description for include about relationship pulling and cost. The tool description adds no parameter-specific meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('App Store version for a build'), distinguishing it from sibling tools like builds__get (reads the build itself) and builds__app__get (reads the app). The endpoint path further clarifies the exact relationship.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing the App Store version for a given build ID, but does not explicitly state when to use it over alternatives or mention exclusions. No sibling differentiation or when-not-to-use guidance is provided beyond the resource name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description reinforces the destructive nature by saying 'unlink' and showing a DELETE endpoint, but it adds no further behavioral context beyond what annotations provide—such as side effects, prerequisites, or reversible/consequences of unlinking.
Agents need to know what a tool does to the world before 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, front-loaded sentence with no filler. It immediately states the action, then includes the endpoint for reference. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple relationship removal with clearly documented parameters and annotations, the description is sufficient. It explains the core behavior and identifies the HTTP endpoint. However, it does not mention that this only unlinks beta groups rather than deleting them, nor does it reference the complementary 'add' operation, which would be useful for full context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both 'id' and 'body' described. The description itself adds no parameter-level information. Since the schema already documents the parameters thoroughly, a score of 3 is appropriate (baseline for full coverage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unlink beta groups from a build' uses a specific action verb and names both the resource being modified (build) and the related resource (beta groups). It also includes the exact REST endpoint, which unambiguously identifies the operation. This clearly distinguishes it from the sibling tool 'builds__beta_groups__add'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but provides no explicit guidance on when to use it versus alternatives (e.g., beta_groups__builds__remove or builds__individual_testers__remove). The usage is implied by the word 'unlink' and the DELETE method, but no clear context or exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds the HTTP endpoint and confirms the read operation but provides no additional behavioral details like response format or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently states the action and resource, making it easy to parse.
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 simple nature and rich annotations, the description is sufficient for an agent to understand its function. Though there is no output schema, 'Read one build' implies the return of a build object, and the schema covers parameters in depth.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (id, include, fields_builds) having descriptive text. The tool description reinforces the 'by ID' parameter but does not add semantic meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies the target resource as 'one build by ID', which precisely distinguishes this tool from sibling tools like builds__list or builds__update. The endpoint path is also provided for confirmation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving a single build when an ID is known, but it does not explicitly state when to use this tool versus alternatives such as builds__list or nested getters. No exclusions or alternative tool mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose read-only, idempotent, and non-destructive behavior, and the description adds minimal context by stating the HTTP GET method. It does not disclose additional behaviors such as pagination details or any limitations beyond what the schema indicates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy, including the endpoint for extra clarity. Every word contributes necessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with no output schema, the description adequately states the tool's purpose and relies on the schema for parameter details. It could be more complete by noting the return contents explicitly, but it is sufficient for this level of complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the parameters. The description does not add any parameter meaning beyond the schema, which is acceptable given the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and identifies the resource 'icons belonging to a build', clearly distinguishing it from sibling tools that list other build-related entities. It also includes the endpoint for reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used when icons of a specific build are needed, but does not explicitly provide when/when-not guidance or mention alternatives. No exclusions or comparisons to sibling list tools are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description adds no extra behavioral context beyond the declared action, such as whether relationships are appended or replaced, or any permission requirements. For a mutation tool, more transparency is expected.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences that state the purpose and the endpoint. Every word earns its place, and no unnecessary information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (nested body object) and the annotations, the description is sufficient for an agent to understand the tool's role. The endpoint and purpose are clear, and the schema handles parameter details. Minor gap: it doesn't explain relationship replacement vs. appending, but this is not essential for basic invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both id and body fully described in the input schema. The description itself adds no additional parameter meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Link individual testers to a build.' This is a specific verb+resource combination that distinguishes it from sibling tools like builds__individual_testers__list and builds__individual_testers__remove. The endpoint reference further reinforces 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?
The description makes it clear this tool is for adding/linking individual testers to a build. It does not explicitly contrast with other add tools like builds__beta_groups__add, but the name and endpoint provide sufficient context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description does not need to restate those. It adds the qualifier 'your response,' which clarifies scope (only the user's own responses). No contradiction with annotations, but no additional behavioral context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that states the action and resource, including the HTTP verb. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and no output schema, the description sufficiently covers what it does. The ID semantics are in the schema, and annotations cover the safety profile. It doesn't explain error cases, but that is not essential for such a straightforward operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'id' has a clear description ('ID from the matching list call'). The tool description adds no extra parameter information, so the 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?
The description uses a specific verb and resource: 'Delete your response to a customer review.' This clearly distinguishes it from sibling tools like customer_review_responses__create and customer_review_responses__get. The HTTP DELETE method is also shown, reinforcing the action.
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 (delete a response) but does not explicitly state when to use this tool versus alternatives or mention any exclusions. It relies on the clarity of the purpose rather than providing guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds resource scope ('logs belonging to a diagnostic signature') but does not disclose additional behaviors such as pagination details, ordering, or rate limits, which are only implied by the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with an endpoint reference, conveying the essential purpose without unnecessary words. It is front-loaded and every element is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with strong annotations and a fully described schema, the description is complete. It lacks explicit mention of pagination or return format, but the schema parameters (limit, next_url) cover pagination, and no output schema is present to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters, with clear descriptions for 'id', 'limit', and 'next_url'. The tool description itself adds no parameter-specific meaning, so the schema carries the full burden. 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 the logs belonging to a diagnostic signature', specifying the verb and resource. It distinguishes this tool from siblings like 'builds__diagnostic_signatures__list' by focusing on logs of a signature. The endpoint reference reinforces the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (when you have a diagnostic signature and need its logs) but does not explicitly state when to use it versus alternatives or mention any prerequisites. The parameter description for 'id' hints at a matching list call, but that is beyond the tool description itself.
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 non-read-only (write) and idempotent behavior. The description adds the PATCH endpoint detail but does not disclose partial update semantics, required fields, or consequences beyond what the schema already shows. With annotations present, the description adds minimal extra 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 a single concise sentence plus the endpoint, with no filler or redundant content. Every word earns its place, and key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with a rich schema and annotations, the description is adequately complete. It conveys the purpose and HTTP method, while the schema covers parameter details and required fields. It lacks explicit usage guidance but is otherwise sufficient for an agent to identify and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with both parameters having clear descriptions: id is 'ID from the matching list call' and body is a 'JSON:API request body'. The description itself adds no parameter information, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('end user license agreement'), with the endpoint pattern providing unambiguous identification. It distinguishes from sibling tools like create, delete, and get by explicitly indicating modification of an existing agreement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The usage is implied by the verb 'Update' and the id parameter, but the description does not explicitly state when to use this tool versus alternatives (e.g., create for new agreements, delete for removal, get for retrieval). No contrast or preconditions are provided in the description itself.
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, and destructiveHint=false, so the safety profile is well covered. The description adds the resource relationship and endpoint but no additional behavioral context (e.g., return format, pagination, errors). It is consistent with annotations, earning a baseline score.
Agents need to know what a tool does to the world before 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 plus an endpoint reference. It contains zero unnecessary words and is immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter GET operation with strong annotations, the description is largely complete. It clearly identifies what is read (the app) and the required input. Though there is no output schema or explicit return shape, the resource type is self-evident, so the short description suffices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the sole parameter ('id') has a helpful description ('ID from the matching list call.'). The description adds no further parameter detail, but with full schema coverage the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Read') and resource ('the app for a pre release version'), which precisely distinguishes it from siblings like pre_release_versions__get (which reads the pre-release version itself) and builds__app__get (which reads an app for a build). The endpoint path reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied rather than explicit. The description means 'use this when you need the app object associated with a pre-release version', but it does not explicitly contrast with alternatives or state when not to use it. Given the simple read nature, it is adequate but with no explicit 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 (destructiveHint=true) already communicate the destructive nature, and the description's 'Delete' is consistent. However, the description adds no extra context such as irreversibility, permissions, or side effects. With annotations covering the safety profile, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It front-loads the action and resource and includes the HTTP endpoint, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter, the description plus schema and annotations provide sufficient context. It does not explain what happens after deletion (e.g., return value, cascading effects), but with no output schema and conservative annotations, this is acceptable. Slightly more detail could be added, hence 4.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a clear description for 'id' ('ID from the matching list call'). The tool description does not add further parameter information. Since the schema already explains the parameter fully, a baseline score of 3 is justified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid 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') and the resource ('routing app coverage'), making it unambiguous. This distinguishes it from siblings like create, update, and get for the same entity. The endpoint specification reinforces the specific operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a straightforward command but does not explicitly state when to use it or contrast it with alternatives. The parameter hint 'ID from the matching list call' implies a prerequisite. Usage is clear from context, but no explicit guidelines or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which fully convey the safe, read-only nature. The description's 'Read' aligns with these hints and adds no extra behavioral context beyond the endpoint. Since annotations carry the safety profile, the minimal additional info merits a 3.
Agents need to know what a tool does to the world before 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, front-loaded sentence with the endpoint appended. It is concise, contains no irrelevant information, and directly communicates the tool's function.
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, strong annotations, and complete schema descriptions, the description is nearly sufficient. It does not explicitly describe the return value (e.g., the full routing app coverage object), but for a GET-by-ID operation this is strongly implied. The only minor gap is the lack of explicit mention of what is returned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (id, include, fields_routingAppCoverages) clearly documented in the schema, including the source of the id and the purpose of include. The description adds no parameter-specific meaning beyond the endpoint, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the operation ('Read'), the resource ('routing app coverage'), and the identifier ('by ID'). This directly distinguishes it from sibling tools like create, update, and delete, and the included endpoint reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for direct ID-based reads but provides no explicit guidance on when to use this tool over alternatives, such as app_store_versions__routing_app_coverage__get which fetches coverage via an app store version. The context is implied by the resource and verb, but no exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnly and idempotent behavior. The description adds minimal behavioral context beyond the endpoint and a parameter hint, and it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences plus the endpoint, with no wasted words. It front-loads the core purpose and keeps the additional hint relevant.
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 listing operation with no output schema, the description adequately conveys the resource type, but it omits any mention of pagination behavior or response structure. The schema covers parameters, but a bit more context on the returned collection would improve 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?
The schema already documents all parameters, so the baseline is 3. The description adds extra semantic value for exists_app, explaining its intended use for existence checks, which goes beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as listing public keys for EU alternative distribution, with a specific verb and resource, and the endpoint is provided. It distinguishes the list operation from sibling get/create/delete tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives one concrete usage hint for the exists_app parameter ('Use exists[app] to check whether an app has one at all'), but it does not explicitly state when to use this list tool versus the sibling get/create/delete operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only provide generic hints (not read-only, not idempotent, not destructive). The description adds critical behavior: 'Submitting an empty list removes the app from all territories; submitting some limits it to those.' This clarifies the replace/clear semantics and goes beyond the schema. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sntences with no wasted words. Purpose, key behavior, and HTTP endpoint are each front-loaded. The critical empty-list rule is succinctly stated and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex nested JSON:API create, the description covers high-level behavior but omits response details (no output schema) and prerequisites or error conditions. It is sufficient for selecting the tool but an agent might need to inspect the schema deeply to construct a valid body correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds semantic meaning for the territoryAvailabilities array (empty list clears fully). However, no explanation is given for required fields like availableInNewTerritories or the included territory attributes, so parameter guidance remains partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 opens with a specific verb and resource: 'Set an app's availability — the countries it is sold in.' This clearly distinguishes the write operation from sibling read tools like app_availabilities_v2__get. The added empty-list semantics further pins down the exact behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (to set or remove territories) but does not explicitly name alternatives or state 'use this instead of get/list.' An agent can infer the write intent from 'Set' and the contrast with sibling get/list tools, but explicit routing guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the agent knows it is a safe read operation. The description adds the endpoint path but no additional behavioral context such as pagination handling or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with the endpoint, front-loaded with the verb 'List' and no extraneous content. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the strong annotations and detailed schema with all parameters documented, the description is sufficient for the agent to understand the tool's purpose and scope. The absence of an output schema is fine because this is a standard list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers 100% of parameters with descriptions, so baseline is 3. The description does not add any parameter semantics beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List the territory availabilities belonging to an app availabilities (v2)' with a specific verb and resource, and includes the endpoint path. This distinguishes it from sibling tools like app_availabilities_v2__get or territories__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 by specifying the parent resource but does not explicitly compare with alternatives or state when to use it. It does not mention prerequisites like needing an ID from a previous list call, though the endpoint path and name convey the relationship to the parent app availability.
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, and destructiveHint=false, so the safety profile is fully covered. The description adds 'Read' and the GET endpoint, which align with the annotations but add no additional behavioral context such as default behavior when no agreement exists 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two terse, information-bearing sentences: the action and the exact endpoint. Every part earns its place, and the core purpose 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?
For a single-parameter read operation with read-only and idempotent annotations, the description is complete. An agent can correctly invoke it by passing an app identifier, and the endpoint clarifies which resource is being fetched. No output schema exists, but the tool is simple enough that return-value details are not required for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There is only one parameter, id, and the schema description covers 100% of its meaning: 'App name, bundle ID (com.example.app) or numeric Apple ID.' The main description does not need to repeat this, and the baseline 3 is appropriate given the schema's full coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb and resource: 'Read the beta license agreement for an app.' The endpoint path ['GET /v1/apps/{id}/betaLicenseAgreement'] makes it explicit that this is the app-scoped variant, distinguishing it from sibling beta_license_agreements__get by agreement ID. No ambiguity about what the tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool — when you need the beta license agreement for an app identified by its app ID. It does not explicitly contrast with sibling tools such as beta_license_agreements__get or beta_license_agreements__list, so the guidance remains implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. However, the description adds no additional behavioral context beyond the basic read semantics, such as return format, pagination, or authorization requirements. It does not contradict the annotations but also doesn't enrich them.
Agents need to know what a tool does to the world before 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 plus the endpoint, front-loading the action and resource. Every word is purposeful with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET-by-ID tool with rich schema descriptions and clear annotations, the description is complete. The absence of an output schema is not an issue since the tool's behavior is straightforward and the parameters are well-documented.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, include, fields_appStoreVersionExperiments) having a description. The tool description itself does not add any parameter-level semantics, but the schema carries the full burden, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read'), the resource ('App Store version experiments (v2)'), and the scope ('by ID'). This distinguishes it from sibling tools like list, create, and update by its specific read-by-ID 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 when to use the tool (when you have an ID and need a single experiment), but it does not explicitly mention alternatives or when-not-to-use scenarios. It lacks a reference to list or other related tools, which would have clarified when this tool is the right choice.
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, so the safety profile is well covered. The description reinforces this with 'List' and a GET endpoint path but adds no additional behavioral context like pagination, authorization needs, or response characteristics.
Agents need to know what a tool does to the world before 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 one concise sentence followed by the endpoint path. It is front-loaded with the action and resource, with zero unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the schema and annotations compensate for much of the missing detail, the description does not mention pagination, return format, or the fact that 10 parameters are available. For a list operation with high parameter count and no output schema, a bit more context would improve completeness, but it remains minimally viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and individual parameter descriptions include valuable details (e.g., territory codes and size warnings). The tool description itself adds no parameter-level meaning, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('customer reviews'), and the scope ('belonging to an App Store version'), which differentiates this from sibling tools like apps__customer_reviews__list or customer_reviews__get. The endpoint path adds further precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The scope is clear: this is for reviews tied to a specific App Store version, not an app-wide review list. However, it does not explicitly mention when not to use it or point to alternatives, such as the app-level customer reviews tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, covering the key behavioral traits of a delete operation. The description adds only the endpoint, not additional behavioral context. With annotations present, the description meets the minimum bar but does not enrich beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus the endpoint. Every word serves a purpose with no filler or repetition. It is as concise as possible while conveying the action.
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 delete operation with one well-described parameter and annotations covering safety and idempotency, the description is complete. No output schema is needed, and the agent has all necessary information to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with a clear description for the only parameter 'id' ('ID from the matching list call'). The tool description adds nothing about parameters, but the schema fully compensates, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: it deletes a beta App Clip invocation. The verb+resource is specific and clearly distinguishes it from sibling operations like get, update, and create on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the verb 'Delete' and the endpoint, but there is no explicit when-to-use guidance, prerequisites, or alternatives mentioned. It is adequate for a straightforward delete operation but lacks any additional context about when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds only the endpoint and 'by ID', which does not disclose any additional behavioral traits beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence plus the endpoint, with no redundant or extraneous information. It is 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 simple get-by-ID operation, the description covers the purpose, the schema covers parameters, and annotations cover safety. The expected return is obvious, so no further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100% with detailed descriptions for all parameters (id, include, fields). The tool description adds no further parameter explanation, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses 'Read one beta App Clip invocation by ID' which is a specific verb+resource, clearly distinguishing it from create/delete/update siblings in the tool set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage when an ID is known to fetch a single invocation, but it does not explicitly mention alternatives or exclusions, such as using a list endpoint for multiple invocations.
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, and destructiveHint=false, which matches the 'Read' description. The description adds no new behavioral context beyond what annotations provide, but not does it contradict them. It is consistent and adequate given the annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the endpoint. Every word earns its place, and it is front-loaded with the action and resource. No unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool, the description, combined with the rich parameter schemas and safety annotations, provides sufficient context. The read behavior is obvious, and no output schema exists to explain. The description is complete for this low-complexity tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions (e.g., 'ID from the matching list call', 'comma-separated list of relationships to include'). The tool description itself adds no additional parameter semantics, but the schema already carries this information, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('beta app review submission') with a clear scope ('by ID'). It distinguishes from siblings like beta_app_review_submissions__list (which retrieves multiple) and beta_app_review_submissions__create (which creates).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for fetching a single record by ID, but it does not explicitly state when to use this tool versus alternatives (e.g., when to use the list tool instead). The parameter description for 'id' mentions 'from the matching list call', which hints at a typical workflow, but there is no direct comparison or exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's 'Read' aligns with annotations (readOnlyHint=true, idempotentHint=true). It adds the endpoint URL but no additional behavioral context such as response size or pagination. Annotations already cover the safety profile, so the description is sufficient but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with the verb and resource, followed by the endpoint. Every word earns its place; no redundant or vague content.
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 straightforward single-get tool with strong annotations and fully described schema, this description is complete enough. The fields parameter enumerates possible return fields, removing the need for a detailed return-value explanation. The sibling list tool provides context for when to use this getter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter details, but schema coverage is 100% with thorough descriptions for id, include, and fields_betaFeedbackScreenshotSubmissions. Since the schema explains the ID source and relationship/field selection trade-offs, the description adds nothing extra.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the resource ('one beta feedback screenshot submission by ID'). It distinguishes from the list sibling by specifying single-resource retrieval via ID.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have an ID, but it does not explicitly mention alternatives or when not to use it. The schema's id description references the matching list call, but the description itself lacks such guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read' is consistent with these. The description adds the HTTP GET path and the 'by ID' scoping, but no further behavioral traits such as error handling, return format, or rate limits. Given the annotations, the description adds minimal but acceptable extra 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 a single, concise sentence that directly states the tool's action and target. It includes the endpoint URL for reference, adding valuable context without unnecessary words. Zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple GET-by-ID tool with strong annotations and comprehensive schema descriptions. The description, while brief, is sufficient for the tool's simplicity: it reads one resource by ID. No output schema exists, but the return value is the beta license agreement as implied by the resource name and the read operation. Sibling tools provide additional context for related operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, include, fields_betaLicenseAgreements) having a meaningful description. The tool description itself adds no parameter-specific semantics beyond saying 'by ID', which aligns with the required id parameter. Since the schema carries the parameter explanation, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one beta license agreement by ID' with the specific verb 'Read', the resource 'beta license agreement', and the scope 'by ID'. It distinguishes from sibling tools like beta_license_agreements__list (reads all) and beta_license_agreements__update (mutates). The HTTP endpoint is also provided, reinforcing the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage is for fetching a single agreement when an ID is available, but it does not explicitly mention when to use this vs alternatives such as the list tool or the related app get tool. The schema's id parameter description ('ID from the matching list call') provides context, but the description itself lacks explicit when-to-use/alternatives 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 signal a non-read-only, non-idempotent, non-destructive operation. The description adds that it sends an email and uses POST, but does not disclose consequences like duplicate invitations or whether the tester must already exist. This adds moderate 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence plus the HTTP endpoint. It is front-loaded with the action verb and contains 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?
The description covers the core action and precondition, and the schema handles the request structure. However, it omits context about the 're-send' semantics (that a new invitation record may be created), potential duplicate emails, and the deprecated betaTester relationship. Adequate but not comprehensive for a mutation tool with a complex nested schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% because the body parameter has a description, so the baseline is 3. The tool description adds no parameter-level meaning and does not address the deprecated betaTester relationship, but with full schema coverage this is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Re-send' with a clear resource ('TestFlight invitation email') and a condition ('to a tester who has not accepted yet'), followed by the exact HTTP endpoint. This clearly distinguishes it from sibling create tools like beta_testers__create and beta_groups__create.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'to a tester who has not accepted yet' provides a clear contextual cue for when to use this tool. It does not explicitly name alternatives or exclusions, but the narrow purpose and condition make the usage context obvious.
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, and destructiveHint=false, and the description matches this by saying 'Read.' Beyond the endpoint and the build relationship, the description adds no additional behavioral context such as response shape, error cases, or auth requirements, so it does not go beyond what annotations already convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by the endpoint, with no wasted words. It is front-loaded with the action and resource, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a simple single-parameter GET operation with strong annotations and a fully descriptive schema. The description plus schema is enough for an agent to select and invoke the tool correctly, and no output schema is needed for this straightforward read.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 one parameter, 'id,' with a clear description ('ID from the matching list call'), achieving 100% schema coverage. The tool description adds the context that this is a build ID, but it does not need to compensate for missing schema information, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and a clear resource ('the app encryption declaration for a build'), and the endpoint path further disambiguates the operation. It distinguishes itself from sibling tools like 'builds__app_encryption_declaration__set' and 'app_encryption_declarations__get' by focusing on the build relationship.
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 clearly indicates this tool is for reading a build's encryption declaration, and the schema adds 'ID from the matching list call,' which gives context for invocation. However, it does not explicitly mention when to prefer this over alternatives (e.g., app_encryption_declarations__get) or state any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as read-only, idempotent, and non-destructive. The description adds the endpoint URL but no additional behavioral context such as pagination behavior or response shape. However, given the strong annotation coverage, the description satisfies the requirement without adding much 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 a single sentence with the endpoint, front-loading the action and resource. It contains no unnecessary words or repetition.
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 straightforward list endpoint with four well-documented parameters and clear annotations, the description sufficiently conveys purpose. No output schema is needed as the endpoint returns a list of builds, which is evident from the description and endpoint path.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters have schema descriptions (100% coverage), so the description need not add parameter details. The baseline of 3 applies because the schema already documents id, limit, next_url, and fields_builds 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 uses a specific verb 'List' and identifies the resource as 'builds belonging to a pre release version', which clearly distinguishes it from sibling tools like 'pre_release_versions__list' or 'builds__list'. The resource relationship is explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool over alternatives, such as 'use this instead of builds__list when you need builds for a specific pre-release version'. The usage is implied by the resource relationship but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral traits beyond the scope (across all apps) and the TestFlight context, which is helpful but not extensive.
Agents need to know what a tool does to the world before 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 with zero wasted words. It front-loads the core purpose and includes the endpoint URL and sibling differentiation.
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 13 parameters, no output schema, and annotations covering safety, the description covers the high-level purpose and scope but doesn't address pagination, sorting, or what fields are returned. It is minimally adequate for guiding selection but not fully comprehensive for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description provides no additional parameter-level meaning. Baseline is 3 as per the rubric, since the schema already documents all parameters thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists version numbers builds were uploaded under, across all apps. It distinguishes itself from a sibling (app_store_versions) by explaining these are TestFlight train versions, not customer-facing App Store versions.
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 ('List the version numbers builds were uploaded under') and when not to ('not App Store versions — for what customers see, use app_store_versions'). It provides a clear alternative but does not elaborate on other conditions 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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description carries a lower burden. It adds meaningful context about state interpretation ('waiting on Apple or on you') and filtering capabilities, but does not disclose additional behavioral traits such as rate limits, pagination behavior beyond what is in the schema, or response structure. This meets the baseline with slight added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, with the first sentence front-loading the core purpose and utility. The second sentence adds filtering and a cross-reference to the sibling tool. The HTTP path is appended clearly in brackets. Every sentence serves a purpose with zero wasted words, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no output schema, and many siblings, the description adequately explains the primary use case and points to the related items list. However, it does not describe the structure of the returned data, the meaning of state values beyond the waiting implication, or the full filtering capabilities. For a list tool with rich parameters, this leaves gaps in what the agent might need to interpret responses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 even without additional parameter details in the description. The description only mentions 'Filter by app or state,' which maps to two of the seven parameters (filter_app and filter_state). It adds no extra meaning for limit, include, next_url, filter_platform, or fields_reviewSubmissions. The reference to review_submissions__items__list is helpful for workflow context but not parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool lists App Store review submissions and their state, with the specific verb 'List' and resource 'review submissions'. It distinguishes itself from the sibling review_submissions__items__list by explicitly noting that items inside a submission come from that other tool, avoiding confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the tool (
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, and destructiveHint=false. The description's 'Read' verb is consistent with these. It adds the endpoint URL as context but does not disclose additional behavioral details like authentication or rate limits. This meets the lower bar due to annotations but adds limited extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence. It states the action, resource, and access method without any filler. The endpoint path is provided in brackets, adding useful technical reference without extra verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool with strong annotations and schema, the description is adequate. It lacks an output schema but the fields parameter controls the response shape. The endpoint path and ID source guidance make this sufficiently complete for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with helpful descriptions for both parameters. The id description explains where to obtain it ('ID from the matching list call'), and the fields parameter explains its purpose and size implications. The tool description itself adds no parameter details, but the schema carries the weight, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Read' with resource 'alternative distribution package delta' and specifies access by ID. It clearly distinguishes from the list operation (alternative_distribution_package_versions__deltas__list) by focusing on a single entity. Including the endpoint path adds clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for retrieving a single delta when you have its ID. It provides context but does not explicitly mention alternatives or when not to use. However, given the sibling list tool, the usage context is reasonably clear.
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, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context beyond the endpoint, but there are no side effects or quirks to disclose. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence conveying the action and resource, with the endpoint appended for precision. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with three well-documented parameters and no output schema, the description is sufficient. It clearly identifies what is listed and the parent entity. Pagination is hinted by the limit and next_url parameters, and no return-format explanation is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all three parameters (id, limit, next_url), so the baseline is 3. The description adds no parameter-specific meaning beyond what the schema already provides, but it also does not need to compensate for coverage 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 action ('List') and the resource ('variants belonging to an alternative distribution package version'), and includes the exact endpoint. It distinguishes from siblings like alternative_distribution_package_variants__get (single variant) and alternative_distribution_packages__versions__list (list of versions).
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 what the tool does, but it does not explicitly mention alternatives or when-not-to-use. However, the resource-specific phrasing makes the intended use obvious, and it is not misleading.
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, fully covering the safety profile. The description adds the scoping constraint 'belonging to an analytics report instance', but doesn't disclose additional behavioral traits such as pagination behavior or response specifics beyond what the schema parameters imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with immediate purpose, followed by the endpoint. No filler or redundancy – every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with clear annotations and 100% schema parameter coverage, the description is sufficient. However, since there is no output schema and the description doesn't describe the response format or pagination behavior, it isn't fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with id, limit, and next_url all described. The description adds no extra parameter meaning beyond the endpoint path, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List the segments belonging to an analytics report instance' with a specific verb and resource, and includes the HTTP endpoint. This clearly distinguishes it from sibling tools like analytics_reports__instances__list (lists instances) and analytics_report_segments__get (gets a single segment).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use it: when you need the segments for a specific analytics report instance, identified by its id. It does not explicitly name alternatives or exclusions, but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description confirms the destructive action and specifies which resource is deleted, adding context beyond the annotations that simply mark it destructive/idempotent. However, it does not disclose other behavioral details such as reversibility or side effects, though the annotations already cover the core safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states the action and includes the endpoint. There is zero waste, and the essential information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with one parameter and strong annotations (destructive, idempotent), the description and schema together are sufficient. It does not explain what happens on success or mention irreversibility, but these are reasonably inferred and not critical gaps for this operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the id parameter described as 'ID from the matching list call.' The description repeats the endpoint placeholder but adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
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') and the specific resource ('an android to iOS app mapping detail'), with the HTTP endpoint providing additional specificity. It unambiguously distinguishes from sibling create/get/update tools for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Delete' and resource name clearly indicate when to use this tool. While it doesn't explicitly name alternatives, the delete action is self-explanatory, and the schema's id description implies a prerequisite (retrieve ID from list call). No exclusions or alternatives are mentioned, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description's 'Read' aligns with these and adds the endpoint URL, but it does not disclose additional behavioral details such as response format or potential errors, which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with the endpoint appended. There is no redundant or tangential information, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with one required parameter, the description, annotations, and schema together provide sufficient information. The only minor gap is that no return value is described, but this is a standard GET and the absent output schema does not create confusion.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 thorough descriptions for both 'id' and 'include', including guidance about pulling related records. The description itself does not add parameter-level detail, so the 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?
The description clearly states the action ('Read'), the resource ('App Clip header image'), and the scope ('for an App Clip default experience localization'). It distinguishes this from sibling tools like app_clip_header_images__get by indicating the resource is accessed through the localization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear when to use this tool: to read the header image for a specific localization. It does not explicitly mention alternatives or exclusions, but the context is straightforward and no conflicting guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is established. The description adds the endpoint and confirms the read behavior, but does not provide extra details like authentication, rate limits, or return structure. Consistent with 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?
One concise sentence plus the endpoint. No wasted 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.
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 complete schema, annotations, and clear purpose, the description is sufficient. It does not explain the output format, but no output schema exists and the resource name implies it. Slight gap about response structure, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, include, fields_...) having its own description. The tool description itself does not add parameter information, but the schema carries the burden. 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 uses a specific verb ('Read') with a precise resource ('App Clip default experience localization') and the method ('by ID'). It clearly distinguishes this from sibling create/update/delete operations and includes the endpoint for additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case: fetching a single localization when you have its ID. It does not explicitly mention alternatives or when-not-to-use, but the context is clear enough for a simple read operation. No exclusions are stated, but none are needed.
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, and destructiveHint=false, and the description's 'Read' and GET method align with these. The description adds minimal additional behavioral context beyond what annotations provide, such as no mention of return format or auth requirements, so this is an average score.
Agents need to know what a tool does to the world before 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, front-loaded sentence followed by the exact endpoint. Every word is useful, and there is no redundancy or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple read operation with fully documented parameters and safety annotations. While there is no output schema, the nature of the resource is clear enough for an agent to know what to expect. It could have described the return object, but the simplicity of the endpoint and the explicit 'review detail' phrasing make it reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully documents both parameters: 'id' is described as 'ID from the matching list call' and 'include' explains when to use it. The description adds no further parameter-specific details, so with 100% schema coverage the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('App Clip App Store review detail for an App Clip default experience'), which is further reinforced by the explicit GET endpoint path. This distinguishes it from sibling tools that operate on other related resources, such as app clip default experiences themselves or standalone review detail endpoints.
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 what this tool is for, but it does not explicitly mention alternatives or exclusions. However, the endpoint path and phrasing make the intended use case unambiguous, so it earns a 4 rather than a 3.
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, covering the safety profile. The description adds the 'Read one... by ID' scope and the specific endpoint, which clarifies the operation's reach. It does not contradict any annotation and provides useful behavioral context (single-item read, not a list or mutation).
Agents need to know what a tool does to the world before 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 includes the operation, resource, and endpoint. There is zero wasted wording, and it is front-loaded with the core action 'Read one App Clip header image by ID'.
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?
This is a simple single-resource GET with no output schema and full schema descriptions for all parameters. The description covers the tool's purpose adequately, and with annotations providing safety details, the minimal description is mostly sufficient. However, it does not explicitly mention any error behavior or response structure, which is a minor gap for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all three parameters (id, include, fields_appClipHeaderImages) having descriptive text. The tool description itself contributes no additional parameter semantic information beyond the schema, so the 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?
The description clearly states 'Read one App Clip header image by ID', specifying the exact verb (read), resource (App Clip header image), and scope (by ID). It inherently distinguishes from sibling tools like create, delete, and update, and is precise about what operation the tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you have an ID and need a single header image) but does not explicitly state when to use this tool over alternatives or mention any exclusions. It relies on the id parameter description in the schema ('ID from the matching list call') for context on prerequisites, but the description itself offers no direct guidance on usage compared to list or update 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 idempotentHint=true and destructiveHint=false, and the description adds no additional behavioral context such as side effects, prerequisites, or response specifics. It does not contradict the annotations, but it also provides no extra transparency beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with the endpoint reference. There is no redundant or vague text, making it maximally concise while still conveying the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema and annotations fully describe the request body and safety traits, making the description sufficient for this straightforward update operation. It omits explicit mention of return values or workflow order, but those are not critical given the simplicity and rich schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides thorough descriptions for both parameters, including the nested JSON:API body with fields and enums. The description itself adds no parameter-related information, so it relies entirely on the schema, which fully covers the semantics. Baseline 3 is appropriate given 100% 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 'Update an App Clip header image' with an explicit HTTP PATCH endpoint, unambiguously identifying the specific resource and action. This distinguishes it from sibling tools like create, delete, or get for the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose is clear enough that an agent can infer when to use this tool: when an App Clip header image needs modification. However, there is no explicit mention of when not to use it or comparison with alternatives like create or get, so it lacks full exclusionary 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?
The annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds that it creates a new language localization and mentions the affected listing fields. However, it does not disclose additional behavioral traits such as required relationship to an app info, potential duplicate errors, or return behavior. Since annotations cover the basic safety profile, a score of 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the endpoint, front-loaded with the core action. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complex nested schema and rich sibling context, the description is adequate for an agent to understand the tool's purpose. The schema fully documents the request body structure, and the description provides the high-level intent. However, it omits the requirement for the 'appInfo' relationship and does not mention that 'locale' is a required field, though these are present in the schema. The overall completeness is good but not perfect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds minimal meaning beyond the schema by naming some fields ('name, subtitle, privacy policy'), but it is slightly inaccurate—it says 'privacy policy' while the schema has 'privacyPolicyUrl', 'privacyChoicesUrl', and 'privacyPolicyText'. The schema itself already provides full parameter details, so the description does not significantly compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add'), the resource ('new language for the app-level listing fields'), and the specific fields involved (name, subtitle, privacy policy). It also includes the REST endpoint, which unambiguously identifies a create operation. This distinguishes it from sibling tools like app_info_localizations__get, __update, and __delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need to add a new language for app-level listing fields. It does not explicitly mention alternatives or when not to use it, but the context is clear enough given the sibling set includes read/update/delete operations for the same resource.
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, and destructiveHint=false, covering the safety profile. The description adds the REST endpoint but no additional behavioral traits such as authentication requirements, rate limits, or side effects. The description is consistent with the annotations and does not contradict them, but it provides minimal extra 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 one concise sentence followed by the endpoint. It is front-loaded with the action and resource, contains no redundant information, and every element earns its place. No filler or unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter, the description is adequately complete. It states the purpose and provides the endpoint, while the schema covers the parameter. There is no output schema, so the description could optionally mention the return format, but 'Read the age rating declaration' strongly implies the response is that declaration. This is sufficient for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter 'id' as 'ID from the matching list call,' so schema coverage is 100%. The description does not add any parameter details beyond the schema. With full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Read the age rating declaration for an app info.' It uses a specific verb ('Read') and a specific resource ('age rating declaration'), distinguishing it from sibling tools like the update variant and other app_info sub-resources. The REST endpoint further clarifies the exact scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need to read the age rating declaration for an app info. It doesn't explicitly name alternatives or exclusions, but the read-only purpose is obvious and the endpoint clarifies the operation. No conflicting usage instructions are present.
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 idempotentHint=true, covering the safety profile. The description adds the relationship scope and endpoint, but does not disclose pagination behavior or response format. This is adequate but not rich, matching the baseline for annotation-covered tools.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the action, and includes the HTTP endpoint for reference. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list tool with full parameter descriptions and safety annotations, the description is largely sufficient. It clearly states what is being listed and the parent resource. It does not detail the response shape or pagination, but those are inferable from the name and purpose; the absence of an output schema makes this a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 6 parameters, so the baseline is 3. The description adds no additional meaning beyond the schema; it only restates the relationship that the 'id' parameter is for an app info, which is already implied by the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' and specifies the resource 'app info localizations belonging to an app info,' clearly identifying it as a collection retrieval scoped to an app info. It is easily distinguished from sibling tools like app_info_localizations__get (single get) and app_infos__get (app info itself).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it lists localizations that belong to an app info, implying the need for an app info ID. It does not explicitly mention alternatives or exclusions, but the scope is unambiguous enough for an agent to know when to use this tool versus other list 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, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds the 'belonging to an app info' scope and endpoint but does not disclose additional behavioral details like pagination or return 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 a single, focused sentence with the endpoint appended. Every word is useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool, the description plus schema and annotations cover the essentials. It lacks explicit pagination behavior, but the schema includes limit and next_url with descriptions, and the operation is straightforward.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are fully described in the schema. The description adds no parameter-specific information, so 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 uses the specific verb 'List' and identifies the exact resource 'territory age ratings' scoped to an app info, with the endpoint clarifying the context. It distinguishes from sibling tools like app_infos__age_rating_declaration__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 clearly implies usage: when you need territory age ratings belonging to an app info, requiring an app info ID. It does not explicitly mention alternatives or when not to use, but the context is unambiguous.
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, covering the safety profile. The description adds the app-scoping constraint but does not disclose additional behavioral details such as pagination semantics or response size implications, though the schema covers some of this.
Agents need to know what a tool does to the world before 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, front-loaded sentence with the endpoint included. Every element is useful and there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation, the annotations cover side-effect safety and the schema covers all parameters. The absence of an output schema is mitigated by the phrase 'List ... requests', which implies the return type. A slightly explicit statement of the response shape would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter descriptions already carry the semantic weight. The tool description adds no parameter-level detail, but per the baseline for full schema coverage, a 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 states a specific verb ('List') and resource ('analytics report requests belonging to an app'), reinforced by the endpoint. This clearly identifies both the action and the app-scoped resource, distinguishing it from other analytics report request operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: the tool lists analytics report requests for a specific app. It does not explicitly name alternatives or state when not to use it, but the app-scoped phrasing gives enough context to route an agent correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is fully covered. The description adds the scoping to a parent app and the HTTP GET endpoint, but does not elaborate on pagination, response shape, or behavior. This matches the bar set for read-only list tools with full annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the verb and resource, then provides the endpoint. Every word is useful and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation, the description plus annotations and fully documented parameters give an agent enough to select and invoke the tool correctly. The lack of an output schema and any description of return fields is a minor gap, but the fields_appTags parameter hints at the available attributes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter already has a meaningful description. The tool description adds no additional parameter-level semantics, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'List the app tags belonging to an app.' The endpoint path [GET /v1/apps/{id}/appTags] reinforces the exact operation and scope. This clearly distinguishes it from sibling tools like app_tags__update or app_tags__territories__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 makes the usage context explicit: use this when you need the app tags for a specific app. It does not explicitly name alternatives or exclusion conditions, but among the many sibling tools there is no closely competing 'list app tags' tool, so the context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds useful behavioral context by framing this as 'Unlink' rather than a full deletion, clarifying that beta tester records themselves are not necessarily destroyed, and the DELETE endpoint reinforces the mutating nature.
Agents need to know what a tool does to the world before 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 purposeful sentence plus the endpoint. There is no filler, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description, combined with the detailed input schema and annotations, is sufficient to invoke the tool correctly. It captures the operation, the relationship-scoped destructive effect, and the HTTP method. The main gap is the lack of explicit disambiguation from closely related sibling tools, but the tool name and endpoint compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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%: both the id and body parameters are well-described in the input schema. The description itself adds no additional parameter-level meaning beyond the endpoint placeholder, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Unlink') and resource ('beta testers from an app'), and the endpoint clearly identifies the operation. This distinguishes it from related but different operations such as beta_groups__beta_testers__remove or beta_testers__delete, despite not naming them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use is directly implied by the action and endpoint: use this when you need to unlink beta testers from an app. However, the description provides no explicit when-not-to-use guidance or mention of alternative sibling tools with similar relationship-removal semantics.
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 communicate read-only and idempotent behavior. The description adds meaningful context beyond those annotations by stating that the result is aggregated time-series data rather than individual records, and by exposing the HTTP endpoint. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tight sentences plus an endpoint reference, with the core behavior front-loaded and no filler. Every sentence contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only metrics tool with complete schema parameter descriptions and clear annotations, the description covers the essential behavior and return type. It could have added pagination or response-shape details, but the aggregated time-series clarification and endpoint make it sufficiently complete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters, including the period enum and groupBy dimension. The free-text description adds no additional parameter-level meaning, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('beta tester usages metrics'), scopes it to an app, and clarifies it returns aggregated time-series data rather than individual records. The endpoint path further pins down the exact operation, and the app-level scope distinguishes it from the beta_groups and beta_testers sibling metrics endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes its app-level context clear and the endpoint path reinforces it, so an agent can infer this is the right tool for app-wide beta tester usage metrics. However, it never explicitly names alternative metrics endpoints or states when to use this one instead of the beta_groups or beta_testers variants.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, and the description's 'Read'/'GET' wording is consistent with those. It does not disclose additional behavioral details such as response shape or relationship-expansion side effects, but nothing contradicts the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded pieces of information: the semantic action and the exact endpoint. Every word earns its place, and there is no redundant filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple read-only nature, the endpoint, parameter schema, and annotations are enough for an agent to invoke the tool correctly. A fully self-contained description might explain what an Xcode Cloud product is or what the response returns, but that is not required for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both id and include have descriptive text, and include has an enum of valid relationship values. The description adds no parameter details beyond the schema, so the baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Begins with a specific verb ('Read') and a concrete resource ('Xcode Cloud product for an app'), and the bracketed endpoint pins down exactly what is fetched. The resource is distinct from the many apps__* and *_get siblings, so an agent can select it without confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly frames the use case: retrieving the Xcode Cloud product associated with an app. It does not name alternatives or exclusions, but no ciProduct-specific sibling exists and the domain is unambiguous.
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, so the safety profile is established. The description adds only the app-scoping constraint and the GET endpoint; it does not disclose pagination or response defaults, but that information is largely carried by the schema. 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?
One sentence with the endpoint suffix, no filler. The core action and scope are 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?
The tool is a simple read-only list with fully documented parameters and strong annotations, and the description gives the essential app-scoped context. No output schema exists, but the fields_customerReviewSummarizations enum and resource name make the return shape inferable. It is adequate without being exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3 and the schema already documents all seven parameters. The description adds no parameter detail, but none is needed given the rich per-field 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 names a specific verb ('List'), a concrete resource ('customer review summarizations'), and the scope ('belonging to an app'). This clearly distinguishes it from sibling review-related list tools such as apps__customer_reviews__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 'belonging to an app' phrasing gives clear context that this endpoint is for app-scoped summarizations and that the caller must supply an app identifier. It does not name alternatives or state when not to use it, but the resource scope is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description aligns with these. The description adds no additional behavioral context such as pagination, error handling, or rate limits, beyond restating that it's a read operation. With annotations present, this is adequate but not enriched.
Agents need to know what a tool does to the world before 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 front-loads the action ('Read'), includes the resource and ID scope, and even embeds the endpoint path. Every element adds value, with no waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID tool with annotations covering safety and schema covering parameters, the description plus structured fields are sufficient. It does not explain return values, but with no output schema, this is not a critical gap for such a standard read operation. The endpoint path adds useful API context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage of all three parameters, each with a clear description (e.g., 'id' explains it comes from a matching list call). The description itself adds no parameter-level meaning, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') with a specific resource ('App Store review attachment') and scoping ('by ID'). The endpoint path is also included, making the operation unmistakable. It clearly distinguishes from create/update/delete and from the list operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates this is for reading a single attachment when you have its ID, providing clear context for use. However, it does not explicitly mention when not to use it or recommend an alternative (e.g., the list endpoint), so it falls short of explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the HTTP GET endpoint and the relationship scope but no extra behavioral details such as pagination, auth requirements, or response format. 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 a single concise sentence that front-loads the verb and resource, followed by the API endpoint. There is no redundant or filler content, making it efficiently scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list tool with 6 parameters, a required 'id', and good annotations, the description adequately identifies the resource and scope, and the schema covers parameter semantics. It lacks explicit mention of pagination or return structure, but 'List' implies a collection, and the endpoint path provides additional context. Not as rich as a fully explanatory description but sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 6 parameters, so the schema already documents each parameter's meaning. The description text does not add any parameter-level detail beyond what the schema provides, so the 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?
The description uses a specific verb ('List') and identifies the resource ('App Store version experiment treatment localizations') with a clear scope ('belonging to an App Store version experiment treatment'). This distinguishes it from sibling tools such as app_store_version_experiment_treatment_localizations__get, __create, and __delete, and from app_store_version_experiment_treatments__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 clearly implies when to use the tool (to list localizations for a given treatment) and the endpoint path reinforces the use case. However, it does not explicitly mention alternatives or when-not-to-use, though the context is strong enough for an agent to select correctly.
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 this as a non-read-only, non-idempotent, non-destructive operation, so the description doesn't need to repeat that. It adds the behavioral fact that this specifically *adds* keywords rather than replacing or removing, which is consistent with the sibling names. It doesn't provide additional side effects or prerequisites beyond what the schema states, so it adds limited behavioral nuance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the endpoint appended, providing maximum information with zero filler. It front-loads the action and purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a relationship-add tool with a nested body, the schema fully documents the required structure, and the sibling tools provide context. The description doesn't explain return values or potential errors, but the absence of an output schema means this is less critical. It's complete enough for an agent to invoke correctly given the schema and naming conventions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with descriptions for both parameters: the id includes 'ID from the matching list call' and the body describes the JSON:API structure. The tool description itself doesn't elaborate on parameters, but the schema already carries the meaning, so this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Add' with a clear resource ('App Store search keywords') and target ('version localization'), and even clarifies the use case ('ASO keyword optimization'). This distinguishes it from sibling tools __list and __remove, so the agent knows exactly which operation is intended.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context for when to use the tool ('ASO keyword optimization') and the action is clear from the name and endpoint. However, it doesn't explicitly mention alternatives like using __remove for deletion or __list for reading, though the sibling names are self-explanatory. This is a minor gap but the usage intent is clear.
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, and destructiveHint=false, so the safety profile is clear. The description adds the scope ('belonging to an App Store version localization') and endpoint, but does not disclose additional behavioral details such as pagination limits or ordering. It is consistent with annotations and adds minimal but useful 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 a single, front-loaded sentence that immediately states the action and resource. It includes the endpoint for context without any unnecessary words. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with full schema coverage and strong annotations, the description is sufficiently complete. It lacks explicit mention of pagination behavior or differentiation from app-level keyword lists, but the schema and endpoint cover the essential context. No output schema is present, so return value documentation is not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 5 parameters, so the schema already explains the meaning of id, limit, next_url, filter_locale, and filter_platform. The description does not add parameter-level semantics beyond the schema, which is acceptable given the 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 uses a specific verb ('List') and resource ('search keywords belonging to an App Store version localization'), clearly distinguishing it from sibling tools like app_store_version_localizations__search_keywords__add/remove and apps__search_keywords__list. The endpoint reference reinforces the exact resource path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the scope: list search keywords for a specific App Store version localization. It implies the use case of reading keywords, but does not explicitly mention when not to use it or alternative list tools (e.g., apps__search_keywords__list). This is clear context without exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the write/safety profile is known. The description adds that this is a RELEASE-level write that publishes immediately, but it does not discuss irreversibility or downstream effects on the live listing.
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 action and precondition are front-loaded, and the endpoint is useful. However, the first two clauses are redundant ('Release the version immediately' vs. 'publish an approved App Store version right now'), and there is an awkward phrase: 'Only for one Apple has already approved.'
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter create with full schema coverage, the description plus annotations give enough context to invoke correctly: the precondition, the action, the endpoint, and the write-level severity. No output schema exists, but return values are not essential for selecting or calling the 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 the nested body structure is already documented. The description adds real semantic value by indicating the appStoreVersion.id should reference an approved version that is waiting on manual release, which the raw schema does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Identifies a specific verb and resource: release an approved App Store version immediately. It also distinguishes itself from the submission workflow with 'manual release button, not the submission,' which helps separate it from related but different 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?
Provides a clear precondition: only for versions Apple has already approved and that are waiting on manual release. It also gives an exclusion ('not the submission'), though it does not name an alternative sibling tool such as release__submit.
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 readOnly, idempotent, and non-destructive behavior, so the safety profile is covered. The description adds no additional behavioral context (e.g., pagination behavior, auth requirements, or response shape) beyond the GET endpoint 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?
The description is a single sentence that immediately states the action and resource, followed by a compact endpoint reference. There is no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple nested list with rich schema coverage and read-only annotations, the description is adequate. It could mention pagination or relationship inclusion, but those are already encoded in the limit, next_url, and include parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each of the 5 parameters including descriptions in the input schema. The description does not add parameter-level detail beyond what the schema already provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a precise resource 'App Store version experiments (v2)' and scoping phrase 'belonging to an App Store version'. The endpoint path makes the parent resource explicit, distinguishing this nested list from sibling tools like apps__app_store_version_experiments_v2__list and single-resource get operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'belonging to an App Store version' clearly indicates when to use this tool: when you have an App Store version ID and need its experiments. It does not explicitly name alternatives or exclusions, but the parent-scoped context is sufficient for selection among sibling list 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=true, covering the safety profile. The description adds the endpoint and 'RELEASE-level write' context, but does not detail behavior like replacing existing links or required build states, so it stays at a 3.
Agents need to know what a tool does to the world before 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 the endpoint provided and no filler. The action is front-loaded and every word contributes useful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With clear annotations and a complete schema, the description is adequate for this simple relationship-update operation. It could mention the response or error conditions, but given no output schema and low complexity, a 4 is appropriate.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 id ('ID from the matching list call.') and body ('JSON:API request body...'). The description adds no additional parameter semantics, earning the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Set') and identifies the exact resource ('build linked to an App Store version'), clearly distinguishing it from related tools like app_store_versions__build__get and builds__app_store_version__set. It also includes the REST endpoint for additional precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear use case (linking a build to an App Store version) and labels it as a 'RELEASE-level write', which implies when it should be used. However, it does not explicitly name alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as a non-read-only, non-idempotent, destructive write. The description adds the useful label 'RELEASE-level write' and clarifies it creates rather than deletes, which prevents misinterpretation. Still, it doesn't disclose additional behavioral traits like duplication risks or state after creation, but the annotation lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it states the purpose in the first sentence, then gives the workflow ordering, then the endpoint and level. Every sentence adds value with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich nested schema and the workflow context in the description, an agent has enough to select and invoke the tool. The end-to-end sequence (create → attach build → submit) is clearly laid out. It lacks output/response expectations, but no output schema exists and the create action's outcome is implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 only parameter 'body' has a schema description, giving 100% schema coverage, so the baseline is 3. The tool description does not add parameter-level guidance beyond 'create a new App Store version', but the nested schema clearly documents required attributes and relationships. No extra semantic value is provided by 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: 'create a new App Store version to prepare' with an explicit resource and verb. It distinguishes this from siblings like update/delete by framing it as 'Start the next release' and referencing the specific endpoint, making its role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit workflow context: 'Do this before attaching a build and submitting for review.' This tells an agent when in the release process to use the tool. However, it does not name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds minimal behavioral context beyond 'Read one' and the HTTP endpoint. It does not mention error handling, rate limits, or response structure, but given the simple read-only nature, this is acceptable; no additional non-obvious behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus an HTTP endpoint notation. It is extremely concise and front-loaded, with no wasted words. Every element contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with a clear ID parameter, the description conveys the essential purpose. There is no output schema, but the description doesn't explain return values. However, the tool's name and the resource concept are self-explanatory, and the schema covers parameters. It is slightly minimal but sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (id, include, fields_betaAppReviewDetails) having descriptive text. The description only mentions 'by ID', which aligns with the required 'id' parameter but adds nothing new. The schema already documents the parameters, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read one beta app review detail by ID' which specifies a concrete action (read) on a specific resource (beta app review detail) with a focus on a single item via ID. This distinguishes it from sibling tools like beta_app_review_details__list (which reads multiple) and beta_app_review_details__update (which modifies).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a known ID and need a single beta app review detail. It does not explicitly contrast with alternatives or list when not to use it, but the 'by ID' phrasing provides clear context that this is for single-item reads, making it distinct from list 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 declare readOnlyHint=true and idempotentHint=true, so the agent knows this is a safe, idempotent read. The description adds the HTTP GET path and specifies it reads one resource, which aligns with annotations. No additional behavioral details (e.g., rate limits, auth) are provided, but the safety profile is covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single declarative sentence plus the endpoint, with no redundancy. It conveys the essential operation in minimal 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 get-by-ID resource with read-only annotations and full parameter descriptions in the schema, the description is adequate. It lacks explicit mention of return format or optional include/fields behavior, but the schema covers those. The absence of an output schema is mitigated by the intuitive read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with descriptions for id, include, and fields_betaBuildLocalizations that explain purpose and trade-offs (e.g., 'comma-separated list of relationships to include'). The main description adds no parameter semantics beyond schema, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the resource ('one beta build localization') and identifies the access method ('by ID'), distinguishing this get-by-ID operation from sibling list/create/update tools. It also includes the REST endpoint for reference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for retrieving a single beta build localization when its ID is known. It doesn't explicitly name alternatives or exclusions, but the 'by ID' phrasing implies the appropriate scenario. Sibling tools like beta_build_localizations__list exist for multiple records, though this isn't stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to repeat that. The description adds the endpoint path but no further behavioral details such as pagination, response shape, or error conditions. This meets the baseline but doesn't add significant value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with the verb and resource, followed by the endpoint URL. There is no extraneous information, making it highly efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with strong annotations and full schema coverage, the description is adequate. It lacks explicit return-value details, but without an output schema and with a clear resource name, the agent can infer what the response contains. The endpoint path adds useful context, though a bit more on behavior or the specific use of the fields parameter could improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 input schema already fully documents both parameters (id and fields_betaRecruitmentCriteria). The description doesn't add parameter-level details, but with complete schema coverage the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' with a clear resource ('beta recruitment criteria for a beta group') and includes the exact endpoint path. This clearly distinguishes it from sibling mutation tools like beta_recruitment_criteria__create, __delete, and __update.
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 verb 'Read' and the resource name make the tool's purpose clear. While it doesn't explicitly say 'use create/update/delete instead for modifications,' the sibling tool names provide that context. The description implies a read-only lookup without exclusions, which is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true. The description adds value by specifying that the operation unlinks (rather than deletes) testers, clarifying the scope of destruction to the relationship only. This context complements the annotations without contradicting them, though it does not mention side effects, authentication, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence followed by the REST endpoint. Every word contributes to understanding the operation, and the most important information (the action and resource) is front-loaded. No filler or redundant phrasing exists.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward relationship removal, the description is largely sufficient. The annotations cover destructive and idempotent behavior, the schema fully documents parameters, and the endpoint clarifies the API contract. The only minor gap is that it does not explicitly mention that the body accepts multiple testers per call, though the schema's array type implies this. Overall, it is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% parameter coverage: 'id' is described as 'ID from the matching list call' and 'body' includes a detailed JSON:API structure. The description itself adds no parameter information beyond what the schema already documents, so it meets the baseline for high schema coverage but does not enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Unlink beta testers from a beta group' with a specific resource and relationship, and includes the exact REST endpoint. This distinguishes it from related removal tools like builds__beta_groups__remove or beta_testers__beta_groups__remove by making the direction and scope of the operation unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by stating the action, and the REST endpoint provides context, but it does not explicitly state when to choose this tool over similar alternatives such as beta_groups__beta_testers__add (the inverse operation) or beta_testers__beta_groups__remove (same relationship from a different perspective). No exclusions or 'when to use' guidance are provided, leaving the agent to infer based on naming conventions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description's 'Read' is consistent. The endpoint is a minor addition, but the description does not disclose other behavioral traits like response size or rate limits. The schema's fields_betaGroups description mentions the 200 KB limit, which adds some transparency, but that is outside the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: one clear sentence plus an endpoint reference. It is front-loaded with the verb and resource, and every element is meaningful with zero waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with three parameters, the combination of annotations and schema is rich. The include/fields_betaGroups descriptions explain relationship costs and response size limits, and the readOnlyHint covers safety. The description itself is minimal but sufficient given the structured context that is already available.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all parameters (id, include, fields_betaGroups) have detailed descriptions in the schema. The description itself adds no extra parameter semantics. Per the baseline rule for high schema coverage, 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Read' and identifies the resource as 'one beta group by ID', clearly distinguishing it from sibling tools like beta_groups__list (reads many) and beta_groups__delete (destructive). The HTTP endpoint [GET /v1/betaGroups/{id}] further reinforces the exact 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?
The description implies the use case: when you have a specific beta group ID and need that single record. The schema's id description ('ID from the matching list call') hints at a list-then-get flow, providing some guidance. However, it does not explicitly name alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the endpoint path but no additional behavioral context (e.g., pagination behavior, response shape), which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus an endpoint reference. Every word earns its place, with no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple list operation, rich schema (all params described), and helpful annotations, the description is sufficient. It defines the scope clearly, though it does not explicitly mention that only builds are returned or the pagination mechanics, which are implied by the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters (id, limit, next_url, fields_builds) are described in the input schema with 100% coverage. The description adds no extra semantic meaning beyond what the schema already provides, so the 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?
The description uses a specific verb ('List') and resource ('the builds belonging to a beta tester'), clearly distinguishing it from sibling tools like builds__list (all builds) and beta_testers__apps__list (apps for a tester). The endpoint path reinforces the scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clarifies the usage context (when you have a beta tester ID and need their builds), but it does not explicitly mention alternatives or when not to use it. The inverse relationship with builds__individual_testers__list is not called out, but the direction is clear from the wording.
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, and destructiveHint=false, so the safety profile is fully covered. The description adds the endpoint and clarifies the resource relationship but does not disclose additional behavioral details like pagination behavior or response format. With annotations present, this is acceptable but not particularly rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence plus endpoint. It contains no filler and directly conveys the tool's purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with strong annotations and complete schema descriptions, the overall context is solid. The absence of an output schema is mitigated by the fields parameter enumerating expected attributes (deviceModel, osVersion, downloadBytes, installBytes). The description could have explicitly noted pagination behavior, but the schema parameters cover it. Minor gap, but generally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly explained (e.g., 'Absolute links.next URL from a previous response'). The description itself adds no parameter details, so it relies entirely on the schema. This 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 'List the build bundle file sizes belonging to a build bundle' uses a specific verb (List) and identifies the exact resource (build bundle file sizes). It clearly distinguishes this tool from siblings like builds__list or build_bundles__app_clip_domain_cache_status__get, and includes the endpoint for additional clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies clear usage context: when you need the file sizes for a specific build bundle. The schema reinforces this with the required id parameter described as 'ID from the matching list call', indicating the need for a prior list call. No explicit exclusions or alternatives are mentioned, but the context is straightforward for a simple list operation.
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, and destructiveHint=false, so the safe read behavior is known. The description adds no further behavioral context, such as response structure, error cases, or pagination. It is consistent with annotations but adds minimal value beyond them.
Agents need to know what a tool does to the world before 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 entire description is one sentence plus the endpoint URL, conveying the tool's purpose and scoping with zero wasted words. The endpoint is a useful, concise addition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with full annotations and complete schema coverage, the description is sufficient. It could mention the return object or explicitly contrast with beta_app_review_submissions__get, but given the simplicity and available structured data, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is already fully documented in the schema as 'ID from the matching list call' (100% coverage). The description does not add any additional semantic meaning, so the baseline score 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?
The description 'Read the beta app review submission for a build' uses a specific verb and resource, clearly scoping it to a build. The endpoint URL further distinguishes it from sibling tools like beta_app_review_submissions__get, which retrieves by submission ID instead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes clear usage context: use this tool when you have a build ID and need its beta app review submission. While it doesn't explicitly name alternatives or exclusions, the 'for a build' scoping makes the intended use unambiguous.
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, and destructiveHint=false, covering the safety profile. The description adds the scoping constraint that results are limited to a single build, but does not disclose other behaviors like pagination details or error handling. With annotations present, this is adequate but not richly detailed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the action and resource, followed by the endpoint reference. Every word serves a purpose with no redundancy or tangential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward list operation with full schema coverage and clear annotations, the description is reasonably complete. It identifies the parent resource (build) and the exact endpoint. The lack of an output schema is mitigated by the simplicity of the tool, though explicit mention of pagination via limit/next_url is left to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all four parameters, achieving 100% coverage. The description does not add additional meaning beyond the schema; the endpoint hints at the 'id' parameter but provides no extra detail. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'List' and specifies the resource as 'beta build localizations belonging to a build.' The endpoint path [GET /v1/builds/{id}/betaBuildLocalizations] reinforces this scope, distinguishing it from the sibling beta_build_localizations__list which likely lists all localizations.
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: use this tool when you need beta build localizations for a specific build, implied by the phrase 'belonging to a build.' However, it does not explicitly mention alternatives or when not to use it, such as using beta_build_localizations__list to fetch all localizations across builds.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructive=true and idempotent=true, and the description adds the HTTP DELETE method and exact relationship path. However, it does not disclose side effects, such as whether the tester is also removed from other contexts or if the operation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single succinct sentence that immediately states the action, endpoint, and target. It avoids redundancy with the schema and annotations, earning a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete relationship operation, the description, combined with the detailed schema and annotations, is sufficient. It specifies the exact endpoint and action, and the schema covers the request body. A minor gap is not mentioning the expected response, but this does not hamper completion for a straightforward delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides full descriptions for both parameters, including 'ID from the matching list call.' The description itself adds no parameter-level details, aligning with the high schema coverage baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Unlink' targeting 'individual testers' from a 'build,' which clearly distinguishes it from sibling tools like builds__individual_testers__add and builds__individual_testers__list. The inclusion of the DELETE endpoint further clarifies the operation type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context (removing individual testers from a build) but does not explicitly mention alternatives or exclusions. The verb 'Unlink' and the presence of sibling add/list tools make the intended use clear, though explicit guidance would strengthen it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, appropriately signaling a safe, non-mutating read operation. The description adds no additional behavioral context such as pagination behavior or response size, but the schema's pagination parameters (limit, next_url) cover that. The description does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus a reference to the endpoint. It is concise, front-loaded with the action 'List', and contains no filler or redundant explanation. Every word contributes to the meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with good annotations and complete schema descriptions, the description is sufficient to understand the tool's purpose and usage. It doesn't explain return values, but the absence of an output schema is offset by the self-explanatory name and endpoint. The tool is straightforward, so this level of detail is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, including details for 'id' ('ID from the matching list call'), 'limit', 'next_url', and 'fields_buildUploadFiles'. The description itself adds no parameter-level semantics beyond the endpoint path, which echoes the schema. Baseline score of 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the specific resource 'build upload files', scoped to 'belonging to a build upload'. This unambiguously identifies the tool's function and differentiates it from sibling tools like build_upload_files__get (a single file getter) or build_uploads__get (the parent resource).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this is for listing build upload files associated with a given build upload. It doesn't explicitly name alternatives or exclusions, but the scope ('belonging to a build upload') makes the intended use obvious. The schema further clarifies that the 'id' parameter is from a matching list call, which supports correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description's 'Read' aligns with the readOnlyHint annotation but adds no extra behavioral context beyond the ID-based single-fetch nature. No mention of auth, rate limits, or relationship fetching trade-offs, though the schema provides some details. Since annotations already establish safety, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence plus endpoint path, with no redundant information. It is front-loaded and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET operation with rich schema descriptions and safety annotations, the description is adequate but minimal. It doesn't explicitly mention return format or that include/fields control response size, but the schema covers these aspects. No output schema exists, so return value details are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, including clear guidance on id sourcing, include relationships, and fields_buildUploads size implications. The description text adds no parameter-specific meaning, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a single build upload by ID, with the specific HTTP endpoint. It distinguishes from sibling tools like build_uploads__delete, build_uploads__create, and list variants.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when one has a build upload ID and needs to fetch that specific resource. It provides clear context but does not explicitly mention alternatives or exclusion cases beyond the inherent 'one' vs 'many' 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 provide readOnlyHint=true, and the description adds the key behavioral detail that the output includes an instruction for grouping by theme. This goes beyond the annotation by disclosing the return format's purpose, though it does not cover pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the primary action ('Fetch recent reviews'), and wastes no words. The enumeration of themes adds necessary detail 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?
With an output schema present and full parameter coverage, the description sufficiently conveys the tool's purpose and output behavior. It lacks explicit alternate-tool guidance, but given the tool's focused role, it is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameters are fully self-documenting. The description adds no additional meaning for app_id, limit, or unanswered_only beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches recent reviews for an app and returns them with an instruction for the agent to group by theme, listing specific themes. This distinguishes it from sibling tools like customer_reviews__list by emphasizing the triage/grouping instruction output.
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 its use case (fetching reviews for thematic grouping) but does not explicitly state when to prefer this tool over alternatives like reviews_ai__daily_briefing or customer_reviews__list. No exclusions or alternative tool mentions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructive behavior, and the description adds the timing constraint ('has not been handed to Apple yet'). This is useful but does not go beyond what the annotations and basic operation imply.
Agents need to know what a tool does to the world before 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 clear sentence, directly stated, plus the endpoint for reference. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a simple single-parameter delete operation with annotations covering destructive behavior, the description is sufficiently complete. It includes the key precondition and clear object of the operation. A small gap is lack of explicit mention of the effects after deletion, but this is minor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage for the single 'id' parameter with a description ('ID from the matching list call'). The tool description adds no additional parameter context, so the schema carries the explanatory burden, warranting the baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('take one item back out') with a clear resource ('submission item') and states the scope ('from a submission that has not been handed to Apple yet'). This clearly distinguishes it from sibling tools like review_submission_items__create and review_submission_items__update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to remove an item from a submission before it has been handed to Apple. It does not explicitly name alternatives or when-not-to-use, but the precondition is clearly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description doesn't need to restate safety. It adds the endpoint path and implies a single-resource read, but does not disclose additional behavioral details such as rate limits, auth requirements, or pagination. This is acceptable given the annotation coverage, but it adds little beyond what is already structured.
Agents need to know what a tool does to the world before 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 states the action, resource, and endpoint. It contains no redundant filler and is well-structured for quick parsing.
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-by-ID operation, the description, combined with the annotated read-only hints and fully documented schema parameters, is complete. No output schema exists, but the resource type and available fields are inferable from the fields parameter enum. The description adequately supports tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already provides rich descriptions for all parameters: id ('ID from the matching list call'), include ('comma-separated list of relationships to include...'), and fields ('Return only these attributes...'). The tool description adds no parameter-level meaning beyond what the schema provides, so the 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?
The description uses a specific verb ('Read') and clearly identifies the resource ('one alternative distribution package version by ID'). It includes the HTTP method and endpoint path, which unambiguously distinguishes this from sibling listing tools and other getters.
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 the use case: fetch a single version by its ID, with ID typically obtained from a list call (as noted in the schema's id parameter). It does not explicitly mention alternatives or exclusions, but the 'by ID' scope and endpoint path provide clear context for when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds the endpoint and precise semantics but no extra behavioral context (e.g., rate limits, error handling, or auth requirements). Since the annotations already handle the key behavioral caveats, a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence plus an endpoint reference. It is concise, front-loaded with the action, and contains no fluff or redundant details.
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 relationship lookup with a single well-documented parameter and strong annotations, the description provides sufficient context. No output schema is present, and the description does not need to explain return values for such a straightforward GET operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the only parameter 'id' has a clear description ('ID from the matching list call'). The tool description adds no additional parameter-level information, so it relies on the schema to carry the meaning—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 uses the specific verb 'Read' and explicitly names the resource ('parent for an app category'), making its function unambiguous. The endpoint [GET /v1/appCategories/{id}/parent] reinforces the action and distinguishes it from sibling tools like subcategories lists.
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 usage is clear from the purpose: use this when you need the parent of a specific app category. The schema's parameter description ('ID from the matching list call') provides contextual guidance that the ID should come from a prior list operation. However, it does not explicitly contrast with alternative tools like app_categories__subcategories__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?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to cover safety. The HTTP endpoint adds a minor implementation detail, but the description adds no behavioral context beyond what annotations provide, such as pagination or ordering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with the endpoint in brackets, making it compact and front-loaded. Every word serves a purpose, and there is no redundant or vague phrasing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list endpoint with no output schema, the description sufficiently conveys what the tool returns (subcategories) and the required context (an app category). The schema covers pagination parameters, and annotations cover safety, so no further details are 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 description coverage is 100%, with all three parameters (id, limit, next_url) already clearly described in the schema. The description adds no additional parameter semantics, so the baseline score 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?
The description uses a specific verb ('List') with a precise resource ('subcategories belonging to an app category'), making the tool's purpose immediately clear. It also distinguishes itself from sibling tools like app_categories__list, which lists categories rather than subcategories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'belonging to an app category' establishes a clear context for when to use this tool: when you need the subcategories of a specific category. It implies a prerequisite (an app category ID) but does not explicitly name alternatives or exclusions, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description reinforces this with a GET endpoint but adds no further behavioral detail such as pagination or relationship inclusion behavior, which are covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, with the core purpose front-loaded and the endpoint annotation as supplementary context. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that all 8 parameters are documented in the schema and annotations cover the safety profile, the description is sufficient for an agent to call this simple list operation correctly. No output schema exists, so return-value details are not required.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 all parameters, including id, sort, limit, include, and filters, are described in the input schema. The description does not add parameter-specific meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('subscription groups belonging to an app'), distinguishing it from sibling list tools like apps__builds__list or apps__list. The scope is precise and the resource is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: this tool is for retrieving subscription groups tied to a specific app, identified by the required 'id' parameter. However, it does not explicitly name alternatives or state when not to use it, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true, so the destructive nature is covered. The description adds the HTTP DELETE method but does not elaborate on side effects, consequences, or required permissions. It does not contradict annotations and provides minimal additional behavioral context beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exceptionally concise: two sentences, each earning its place. It states the operation, the target resource, and the endpoint, with zero filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with a single parameter and no output schema, the description is fully sufficient. It covers the action, resource, and endpoint, while the schema covers parameter semantics. No additional context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool description itself does not add parameter details, but the schema provides 100% coverage with a helpful description ('ID from the matching list call.') telling the agent where to obtain the ID. This meets the baseline for high schema coverage, but the description does not go beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete'), the resource ('a beta feedback screenshot submission'), and includes the HTTP endpoint. It is unambiguous and distinct from sibling tools like the crash submission delete or listing/getting screenshot submissions.
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 usage context is clear: use this to delete a specific screenshot submission. The parameter description in the schema adds the prerequisite of getting the ID from a list call. However, it does not explicitly contrast with alternative operations (e.g., get, list) or mention when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. The description adds no additional behavioral context (e.g., auth requirements, rate limits, or side effects), but it also does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and target resource, followed by the endpoint. There is no unnecessary repetition or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation with good annotations and complete parameter schemas, the description is sufficient. It clearly tells the agent what the tool does and leaves parameter details to the schema, which is complete. No output schema exists, but the return value is implicitly the requested customer review response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the id, include, and fields_customerReviewResponses parameters. The description itself adds no parameter-level detail, but the schema descriptions are thorough (e.g., 'ID from the matching list call', cost of includes, 200 KB row size), so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and the specific resource ('one customer review response by ID'), making the tool's purpose immediately obvious. It also includes the HTTP endpoint, further disambiguating it from related siblings like customer_review_responses__create or customer_reviews__response__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 context: you should use this tool when you have an ID of a customer review response to read. It does not explicitly mention alternatives or exclusions, but the operation is simple and self-evident from the description and the parameter description ('ID from the matching list call').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the GET endpoint and the scope, but does not disclose additional behavioral details such as pagination behavior or response format beyond what annotations and schema 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 sentence that effectively states the action, the resource, and the endpoint. It is front-loaded and contains no filler or redundant 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 straightforward list operation with full schema coverage and clear annotations, the description is sufficient. It clearly states what is being listed and for which entity, and the schema handles pagination and field selection details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, including explicit descriptions for all four parameters (id, limit, next_url, fields_territories). The description itself adds no parameter semantics beyond the endpoint placeholder {id}, so the baseline score 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?
The description uses a specific verb 'List' and clearly identifies the resource 'territories belonging to an end user license agreement', which distinguishes it from sibling tools like territories__list or app_tags__territories__list. The endpoint in brackets further clarifies the exact 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?
The description clearly conveys that this tool is for listing territories scoped to a specific end user license agreement, providing strong contextual cues. However, it does not explicitly mention when to avoid using it or name alternatives, though the scope is unambiguous.
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, and the description does not contradict them. It adds valuable context beyond those annotations: authentication requirements (vendor number + Finance role), the HTTP endpoint, and the critical default behavior that the raw response is a gzipped blob unless parse=true. It does not mention rate limits or pagination details, but those are partially covered by the next_url parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: purpose first, differentiation second, then requirements and format behavior. Every sentence earns its place. It loses one point because the raw '[GET /v1/financeReports]' endpoint string is redundant for an agent selecting a tool, and the parse=true guidance partially duplicates the schema's parameter description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must disclose return behavior, and it does: raw gzipped blob by default, decoded rows with parse=true. It covers prerequisites, scope (region, currency, fiscal period), and the parse/max_rows/next_url mechanics are in the schema. Gaps are minor for a read tool: no mention of pagination flow, no format guidance for filter values (dates, region codes), and no explicit note that all four filters are required.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 carries the parameter-documentation burden and the baseline is 3. The description adds marginal value by mapping ASC_VENDOR_NUMBER to the vendorNumber filter and hinting at parse=true, but those points are already well explained in the schema (e.g., parse's description covers gunzip, TSV decoding, and the response shape). Filter value formats for regionCode and reportDate are not elaborated anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb + resource ('Download the monthly financial report') and defines what the content is: 'what Apple actually paid, by region and currency, for a fiscal period.' It proactively differentiates from the units-sold sibling ('This is the money report, as opposed to units sold'), which distinguishes it from sales_reports__list without any ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: it is the financial/money report rather than units sold, and it states explicit prerequisites ('Needs ASC_VENDOR_NUMBER and a Finance role on the API key') plus a format-selection hint (parse=true for decoded rows). It does not name the sibling tool sales_reports__list explicitly, so the exclusion is implied rather than fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a destructive write operation (readOnlyHint=false, destructiveHint=true). The description adds context beyond that by specifying 'RELEASE-level write', the 'open review submission' prerequisite, and the one-item-per-call constraint. No contradiction exists between the description and annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two tightly worded sentences, front-loaded with the action and resource, followed by a single-item note and an endpoint reference. Every clause carries meaning; there is no filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the nested schema and lack of an output schema, the description covers the core action and constraint but omits explicit guidance on prerequisites (e.g., ensuring the review submission is open and obtaining the submission ID) and expected response behavior. It is minimally viable but leaves some gaps for a complex create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema's single required 'body' parameter is described as a JSON:API request body, providing baseline coverage. The description adds examples of acceptable item types (version, event, releasable item) but does not explain how to populate the nested relationships or required fields, which the schema already details via properties. This meets the baseline but does not go beyond 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 uses a specific verb ('Put') and resource ('review submission item'), clearly indicating this creates an item within an existing review submission. It further distinguishes the tool from siblings like review_submission_items__delete and review_submission_items__update by operation type and from review_submissions__create by the item-level scope. The phrase 'One per call' adds an important behavioral clarification.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool: to add a version, event, or other releasable item to an open review submission, and to repeat the call per item. This provides clear usage context, though it does not explicitly name alternatives or exclusions. The 'open review submission' constraint is a useful contextual cue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already provide readOnlyHint=false, idempotentHint=true, and destructiveHint=false, so the core behavior is covered. The description adds only the HTTP method (PATCH), which hints at partial update semantics, but doesn't elaborate on overwrite behavior or return values.
Agents need to know what a tool does to the world before 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 plus endpoint, with zero filler 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 rich schema detailing all updatable attributes and the annotations covering idempotency and non-destructiveness, the description is adequate for invocation. It lacks explicit return-value information and partial-update behavior, but these are not critical for a straightforward PATCH operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage: id is described as 'ID from the matching list call' and body as 'JSON:API request body (Apple schema: AccessibilityDeclarationUpdateRequest).' These descriptions add practical context beyond the schema's type definitions, particularly for obtaining the ID and the API format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('an accessibility declaration'), with the HTTP endpoint PATCH /v1/accessibilityDeclarations/{id} distinguishing it from create/delete/list 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 implies this tool is for modifying an existing accessibility declaration, and the id parameter description 'ID from the matching list call' provides a prerequisite. However, it doesn't explicitly contrast with create/delete 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 declare readOnly, idempotent, and non-destructive. The description adds useful behavioral context about response size ('A full row set can exceed 200 KB') and the ability to limit fields, which is 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the endpoint, conveying the action and resource without unnecessary words. It is well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple GET operation with no output schema, the description covers the resource, action, ID source, and optional field selection with a size warning. It does not describe the response structure or error cases, but these are less critical given the simplicity and available annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, clearly explaining the id's source and the fields parameter's purpose. The description adds no extra parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and specific resource ('one alternative distribution key by ID'), with the exact endpoint provided. This unambiguously distinguishes it from siblings like alternative_distribution_keys__list (read many) and create/delete mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context for when to use this tool: when you have a specific ID. The parameter description 'ID from the matching list call' implies a workflow of listing first. However, it does not explicitly mention alternative tools 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 cover the safety profile (write operation, idempotent, non-destructive). The description adds behavioral detail beyond that: the per-language effect scope, the 30-character limit on name and subtitle, and the PATCH method which implies partial-update semantics. It does not contradict any annotation.
Agents need to know what a tool does to the world before 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 carrying exactly three useful pieces of information: action + fields + scope, the length constraint, and the endpoint path. The verb is front-loaded, there is no fluff, and nothing is repeated from the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a moderately nested 2-parameter update with full schema coverage and safety annotations, the definition gives an agent what it needs to call correctly: target ID origin (schema), field structure (schema), and key constraints and scope (description). Minor gaps: null-field behavior is unspecified and no disambiguation from app_store_version_localizations__update is 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%, so the baseline is 3. The description adds genuine value beyond the schema by mapping 'name' to the domain meaning 'listing title' — resolving an ambiguity the bare string field cannot — and by disclosing the 30-character cap that the schema's nullable-string declarations do not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (update), resource (app info localization / listing metadata), and scope (one language), and maps the ambiguous Apple field to a domain concept ('listing title (Apple's field is called the name)'). This clearly differentiates it from sibling localization updates such as app_store_version_localizations__update, and the endpoint path provides a concrete identity anchor.
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 'for one language' scope and the 30-character cap give some usage context, but the description never states when not to use the tool or names an alternative (e.g., app_store_version_localizations__update for version-specific metadata, or app_info_localizations__create when the localization row does not yet exist). Usage must be inferred rather than guided.
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 (readOnly=false, idempotent=true, destructive=false) already establish the safety profile. The description adds non-obvious behavioral context beyond that: changes propagate to every version because categories are app-level rather than version-level. The PATCH endpoint is also disclosed. No contradiction — 'Change' aligns with readOnly=false and idempotent PATCH semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero fluff: the first states the action, the second delivers the critical scope side-effect, and the endpoint is appended for reference. Every sentence earns its place and the most important constraint is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating PATCH tool with no output scheema, the description covers the essential effect (propagation to all versions) and the scheema documents the nested payload structure for all six category/subcategory relationships. Minor gaps remain — whether omitting a relationship clears it, and required permissions — but the core call path is well-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: id is described as 'ID from the matching list call' and body as 'JSON:API request body (Apple schema: AppInfoUpdateRequest).' With full schema coverage the baseline is 3. The description adds slight semantic value by mapping the abstract relationship fields to the concepts of primary/secondary categories and subcategories, but doesn't clarify partial-update or clearing behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Change an app's primary and secondary App Store category and its subcategories.' It states exactly what is mutated and narrows the scope versus version-level tools by noting the entity persists 'for every version,' distinguishing it from related siblings like app_store_versions__update and the read-only app_infos__* getters.
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 second sentence gives clear scoping context: categories 'belong to the app rather than to a version,' so this tool is the right choice for app-wide category changes and is implicity contrasted with version-scoped updates. It doesn't explicitly name alternative tools or state when-not-to-use, but the app-vs-version distinction is strong enough to route an agent correctly.
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, and destructiveHint=false, covering the safety profile. The description adds that this is a lookup used for future price-setting, but does not disclose additional behavior such as pagination limits or silent empty-result behavior. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences plus an endpoint reference with no filler. The primary purpose is front-loaded, followed by a practical use case, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete enough for a list operation: it states what is listed, how to narrow it, and the purpose of the result. With no output schema, a slightly more explicit statement of the response shape would help, but 'find the price point ID' reasonably implies the output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining that filter_territory is how you locate a price point ID for a target price, which enriches the otherwise generic schema parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and a specific resource ('allowed price points for an app's purchase price'), plus the exact endpoint. It clearly distinguishes this from siblings like pricing__set_subscription_price or apps__app_price_schedule__get by focusing on retrieving price-point 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 gives practical guidance: filter by territory to find the price point ID matching the price you want to set. It does not explicitly name alternatives or when-not-to-use cases, which prevents a 5, but the intended use 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 mark this as destructive, non-read-only, and idempotent. The description adds useful context beyond those hints by clarifying what is destroyed: the entire current set of promoted purchases, and by flagging it as a REVENUE-level write. 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 compact sentences front-load the action and resource, then add the endpoint and a severity cue. No filler or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter replace operation with fully described schema fields and annotations covering destructive/idempotent behavior, the description is complete enough. It lacks an explicit statement about removal of omitted promoted purchases, but 'full set' plus destructiveHint covers the key agent decision.
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 the baseline is 3, but the description's 'full set' language adds meaning to the body parameter: the data array must represent the complete desired relationship set, not a delta. This is not explicit in the schema itself.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific verb and resource: 'Replace the full set of promoted purchases linked to an app.' The 'full set' wording distinguishes this from related read tools like apps__promoted_purchases__list, and the PATCH endpoint confirms the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'Replace the full set' implies the tool is for wholesale replacement rather than listing or incremental changes, but it does not explicitly name alternatives or state when not to use it. The 'REVENUE-level write' tag adds a caution signal but no routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. The description adds a useful nuance about halting preserving readability, which goes beyond annotations, but it does not disclose other potential side effects like starting conditions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that front-load the main action, include an HTTP endpoint hint, and avoid unnecessary detail. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update tool with 100% schema coverage and no output schema, the description covers core behaviors and the important halt-vs-delete nuance. It doesn't explain the request body structure, but that is already in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only provides generic descriptions for id and body. The description's 'begin or halt' maps to the 'started' attribute and 'traffic split' maps to 'trafficProportion', adding meaningful semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Change a product page experiment' with specific operations (begin, halt, adjust traffic split). This distinguishes it from sibling tools like create, get, or delete for experiments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides a usage distinction: 'Halting it keeps the results readable; deleting does not.' This hints at when to use update (to halt) versus delete, but does not explicitly enumerate all alternatives or 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 already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds value by revealing the exact API endpoint and implying pagination (via the 'limit' and 'next_url' parameters). No contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately conveys the action and scope, followed by the endpoint URL for reference. Every word is necessary, and there is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 8 parameters, no output schema, and high schema coverage, the description is adequate for a list operation. It does not explain return value structure or pagination behavior beyond what the parameters hint at (limit, next_url). However, for a straightforward list tool with safe annotations, this level of detail is sufficient. A slightly more complete description could mention pagination or that it returns a list of screenshot set objects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-specific details, but the schema already provides rich descriptions for each parameter, including enum values, filtering behavior, and usage notes (e.g., 'ID from the matching list call' for the required 'id' parameter). The description's lack of extra param info is acceptable given the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List'), the resource ('app screenshot sets'), and the parent scope ('belonging to an App Store version localization'). It includes the exact HTTP method and endpoint URL, which is a strong differentiator from sibling tools like 'app_store_version_localizations__app_preview_sets__list' or 'app_store_versions__app_store_version_localizations__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 provides no explicit guidance on when to use this tool versus alternatives (e.g., 'app_store_version_localizations__app_preview_sets__list'). While the name and resource context make it clear this is for screenshots specifically, there is no mention of prerequisites (like needing a localization ID first) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the HTTP method PATCH, which hints at partial update semantics, but does not elaborate on side effects or any remaining behavior beyond what annotations offer.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, information-dense sentence that lists the key updatable fields and includes the endpoint path. Every word adds value, with no fluff or unnecessary repetition of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given it is an update operation with two parameters and no output schema, the description adequately covers purpose and fields. It omits an explicit note that unspecified fields remain unchanged (a typical PATCH semantic), but the PATCH notation in the description partially hints at that. Overall, it is sufficiently complete for an update tool with detailed annotations and schema descriptions.
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 both 'id' and 'body'. The description adds context by listing the editable fields (description, keywords, what's new, promotional text, support/marketing URLs), which semantically groups them as 'store listing text' and clarifies what the body payload should contain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action ('Update') with a clear resource ('store listing text for one language of a version') and enumerates the exact fields involved. This clearly distinguishes it from sibling create/delete/get operations on the same resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'Update' and the phrase 'for one language of a version' provide clear context that this tool is for modifying an existing localization. However, it does not explicitly state alternatives such as 'use create for new localizations' or 'use delete for removing', so it lacks explicit when-not 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?
Given existing annotations (readOnlyHint=false, destructiveHint=true), the description adds useful context: the rollout spans 7 days, targets approved versions, and is a write operation. It doesn't contradict annotations, though it doesn't elaborate on the destructive implications.
Agents need to know what a tool does to the world before 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 convey the purpose, duration, prerequisite, HTTP method, and operation level. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with no output schema, the description adequately explains the action, duration, and prerequisite. The nested body schema handles the structural details; the description adds the high-level purpose and conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of the parameters (body), and the description adds no parameter-specific guidance. The baseline of 3 applies because the schema itself provides the necessary structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action (Start a phased rollout), the target resource (approved version), and the key behavior (gradual percentage increase over 7 days). It also includes the HTTP endpoint, distinguishing it from related operations like update or delete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear prerequisite ('approved version') and implies when to use it (to begin a rollout). It doesn't explicitly mention alternatives like update or delete, but the context of a create operation is evident from the name and description.
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 signal write/destructive/idempotent behavior; the description adds context beyond that with 'RELEASE-level write' and the specific state transitions. This helps the agent understand the operation's scope and 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?
The description is two sentences, front-loaded with the primary action and including only necessary operational details. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the operation, endpoint, state changes, and release-level write context. While it does not describe return values, there is no output schema and the operation is a straightforward write. The PAUSE/PAUSED mismatch is a minor completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides 100% parameter coverage, including 'ID from the matching list call' and the JSON:API body schema with the phasedReleaseState enum. The description adds little beyond what the schema provides, and it introduces a minor inaccuracy by saying 'PAUSE' instead of the schema's 'PAUSED'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid 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 and resource: 'Pause, resume or complete a phased release' and specifies the state changes via 'Set phasedReleaseState to PAUSE, ACTIVE or COMPLETE.' It distinguishes itself from sibling tools like create and delete by focusing on updating an existing phased release. The minor PAUSE/PAUSED inconsistency does not obscure the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: to pause, resume, or complete a phased release, with the specific state values listed. It does not explicitly address exclusions or alternatives, but the scope is narrow and the intended use is obvious.
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 the description adds meaningful behavioral context: it returns an aggregate across all apps, includes live and in-flight versions, and translates states into implied actions. This goes beyond the annotation without contradicting it.
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 tight, front-loaded, and well-structured, with the core behavior first and details following. The only minor redundancy is the final 'Read-only,' which duplicates what the annotation already states.
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 an account-wide read-only status tool with an output schema and a fully described optional parameter, this description is complete. An agent can correctly decide when to call it and what kind of results to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools 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 single parameter only_actionable is already fully documented in the schema. The description does not itself explain that parameter, but given the schema covers it, a 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 states a specific verb ('Show every app in the account') and resource (account-level status), and clearly differentiates itself from single-app tools by saying 'rather than one app.' It also explains the value-add: translating App Store states into implied actions, so an agent immediately understands what this tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear trigger: 'Start here when the question is "what needs my attention?" rather than one app.' This provides strong contextual guidance, though it does not name a specific alternative tool or explicitly state exclusions beyond the single-app contrast.
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 declare readOnlyHint=false, idempotentHint=false, destructiveHint=false, so the agent knows this is a non-idempotent write. The description adds the key behavioral context about external groups requiring Apple review before receiving builds, which is valuable. It does not disclose details like required app relationship or that builds can be linked at creation.
Agents need to know what a tool does to the world before 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 front-loads the purpose, names the key distinction (internal vs external), and includes the endpoint 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?
The description covers the tool's core purpose and key behavioral distinction, while the schema fully documents required fields (name, app relationship) and optional attributes (feedbackEnabled, publicLink, etc.). The missing output schema is acceptable for a create operation whose response mirrors the request in Apple's API. Could slightly benefit from mentioning that an app relationship is mandatory, but the schema carries that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 1 parameter with 100% description coverage (the body is explained as the JSON:API request body). The description adds meaning by framing the purpose (organizing testers, internal vs external), which helps the agent understand the relationship and attributes. The schema itself is deeply nested but well-typed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious 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 a clear verb ('Make a TestFlight group') with a specific resource, and distinguishes the two main use cases (internal team vs external Apple-reviewed) directly in the text. It also maps to the endpoint [POST /v1/betaGroups], making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly conveys when to use this tool: creating a TestFlight group, and distinguishes internal vs external groups with different review implications. It doesn't explicitly name alternative tools, but the sibling list shows related beta_group operations with different verbs (list/get/update/delete), making the use case clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is known. The description adds the important behavioral fact that output is aggregated time-series data, not individual records, which goes beyond the structured annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, information-dense sentences with the endpoint template included. Every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only metrics endpoint with no output schema, the description communicates the key return shape (aggregated time series) and scope (per beta tester). It does not enumerate specific returned metrics or mention required filter_apps, but schema covers parameters and the description is sufficient for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover all four parameters (id, limit, period, filter_apps), including enum values, so the description adds no parameter-level detail. The baseline of 3 applies because schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Read' and the specific resource 'beta tester usages metrics' for a beta tester. The clarification 'aggregated time-series data, not individual records' distinguishes it from individual record tools and sibling metrics endpoints.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives useful context by noting the tool returns aggregated metrics rather than individual records, which helps the agent decide when to use it. It does not explicitly name alternatives or exclusions, but the aggregated-vs-individual distinction provides clear usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context that annotations already declare readOnlyHint and idempotentHint. It discloses the endpoint path and the fact that this is a list operation. The description does not contradict annotations (no annotation_contradiction). It provides enough behavioral transparency for a read-only, idempotent list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with zero wasted words. It front-loads the purpose, immediately distinguishes from a sibling, and ends with the endpoint path. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters (all optional), 100% schema coverage, no output schema, and is a straightforward list endpoint, the description is mostly complete. It explains the core purpose and relationship to sibling tools. A minor gap is not explaining pagination behavior or that the 'build' filter expects a specific ID format, but the schema descriptions cover that partially.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add any parameter-specific meaning beyond what the schema already provides. For example, it doesn't explain how 'include' with 'build' relationship works or what the filter parameters expect. The description could have elaborated on the relationship between build IDs and this endpoint.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'TestFlight state of builds', and immediately distinguishes itself from the sibling tool 'builds__list' by noting that this is the 'beta side of a build' whereas build attributes come from that other tool. It also specifies the exact fields returned: whether external testing is available and how the build was distributed.
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 (to get TestFlight/beta state) and explicitly contrasts it with builds__list for build attributes. However, it does not state when NOT to use this tool or mention any prerequisites, such as needing a build ID first.
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, covering the safety profile. The description adds behavioral context about the return format ('aggregated time-series data, not individual records') and the endpoint path, providing value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, packed sentence followed by the endpoint. It conveys purpose, output type, and a key exclusion without waste. Every element earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two documented parameters and full annotations, the description covers the essential purpose and output shape. It could more explicitly define what 'usages metrics' includes, but the current wording is sufficient for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both 'id' and 'limit' have descriptive texts. The description itself does not elaborate on parameters beyond what the schema provides, so it meets the baseline without additional value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read'), the resource ('beta build usages metrics'), and the scope ('for a build'). It also distinguishes itself from related metrics tools by specifying 'aggregated time-series data, not individual records', which aligns with the tool's unique purpose among siblings like beta_groups__public_link_usages__metrics.
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 appropriate use: when you need aggregated beta build usage metrics for a specific build, and explicitly excludes individual-record queries. However, it does not name alternative tools or state when-not-to-use it, so it falls short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey that this is a non-read-only, non-destructive, idempotent operation. The description adds the distribution-compliance context but does not disclose additional behaviors such as response details or side effects. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and endpoint, followed by the most relevant purpose. It contains no filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The nested body structure is fully documented in the schema, so the description does not need to repeat it. The description provides the real-world motivation for the update, which is helpful for selection. It could mention other updatable fields like expired, but the schema already covers them.
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 the schema fully documents both parameters. The description adds semantic meaning by identifying usesNonExemptEncryption as the key compliance field, which goes beyond the raw schema names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('Update a build') and adds the common use case of setting usesNonExemptEncryption compliance. This clearly distinguishes it from sibling read/list tools like builds__get and builds__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 provides a clear context for when to use the tool ('most commonly to set usesNonExemptEncryption compliance so it can be distributed'). It does not explicitly mention alternatives or exclusions, but the endpoint and common use case give sufficient 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 indicate creation (not read-only, not idempotent). Description adds the behavioral constraint of one response per review, which is beyond annotation info. 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, no wasted words. Front-loaded with verb and resource. Extremely concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the nested schema and no output schema, the description provides the constraint and update alternative. Lacks detail on return value or side effects, but overall adequate for a creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and fully documents the nested body parameter. Description does not add additional semantics beyond the schema, which is acceptable. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (publish a developer response) and the resource (customer review). It distinguishes from the sibling 'update' tool by noting the one-response-per-review constraint. Includes HTTP method for clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool: to create a response, and when to use update: to change it. The one-response constraint guides usage. Could add prerequisites like needing the review ID, but 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?
The readOnlyHint annotation is present, and the description goes beyond it by specifying the audit's scope, the kinds of issues reported, and the no-mutation guarantee. It does not describe response structure or edge cases, but the annotation lowers the burden and the description adds meaningful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no filler: the action and resource are front-loaded, concrete examples are packed into the em-dash list, and the read-only clarification is isolated for emphasis. Every sentence contributes.
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?
This is a simple two-parameter tool with one required parameter, full schema coverage, and a read-only annotation. The description provides enough behavioral context for an agent to select and invoke it correctly, though the exact report output format is not specified since no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already documents both parameters thoroughly, including the version default, so the description does not need to add parameter syntax. It adds some conceptual context by tying the audit to 'store text' and 'every language,' but that does not go beyond the schema's coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific action ('Compare an app version’s store text... and report') on a concrete resource, then lists exact defect categories: empty descriptions, blank keywords, and language-coverage gaps. It also clarifies what the tool does not do, setting it apart from sibling apply/draft 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 clearly frames the tool as a read-only audit and explicitly states it 'reports and stops' and 'never fills anything in,' which signals when to use it and when not to use it. It does not name sibling alternatives like metadata_ai__apply_localizations, but the context is strong enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as destructive, and the description adds significant context: 'REVENUE-level write covering about 175 countries' and clarifies that prices are not copied across currencies but derived by Apple's tax/currency logic. The dry-run recommendation adds caution, though the dry-run flag is not present in the schema, which may cause minor confusion.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: three sentences that lead with the core purpose, then give a compact how-to with examples, and end with an important operational warning. Every sentence adds value and there is 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?
The description is mostly complete for a write tool: it explains the scope, examples, and suggests a dry-run to see derived prices. However, it does not mention what the actual response/return value contains (no output schema), nor prerequisites like permissions or app existence, which would improve completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 100% of parameters with detailed descriptions. The description reiterates the anchor territory and price format with examples, and clarifies product_type scope, but does not add new semantic detail beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Set one anchor price and let Apple derive the equivalent price in every other country, for an app, an in-app purchase or a subscription.' It specifies the exact resource scope and differentiates from sibling tools like pricing__set_subscription_price by emphasizing currency-based equalization across ~175 countries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage context: use it when you want Apple to derive equivalent prices across territories, with examples (TUR, 99.99) and an explicit warning to run under --dry-run first. However, it does not explicitly contrast with alternatives or state when NOT to use it (e.g., when you want a simple non-equalized price set).
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 it is read-only and non-destructive. The description adds context that it reveals the state of each item and what Apple will see, plus the exact API path and method. It does not disclose pagination behavior, but annotations mitigate safety concerns.
Agents need to know what a tool does to the world before 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 the API endpoint. No fluff, front-loads the action and resource, and every word contributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with strong annotations and a complete schema. The description explains the purpose and what the response contains (items and their states), which is adequate. Could mention pagination but not critical given schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All parameters are fully described in the schema (100% coverage). The description adds no additional parameter semantics beyond what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists items inside a review submission and their state, with a specific use case. This differentiates it from siblings like review_submissions__list (lists submissions) and review_submission_items__create/update/delete (mutations).
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: use it to inspect the contents of a review submission before submission. It does not explicitly name alternatives or exclusions, but the purpose strongly implies when to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already denoting a safe read, the description adds valuable behavioral context: it searches domains not loaded and returns specific fields (tool names, domain, endpoint). It also highlights the English-only matching behavior, going beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences deliver purpose, return information, and a critical usage constraint. The structure is front-loaded with the core action and remains free of redundant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, output, and language behavior. Given the simple schema and the nature of a search/discovery tool, no additional behavioral details are necessary for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for both parameters. The description reinforces the English-only requirement for the query and mentions the search scope, but adds little semantic value beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a search operation for App Store Connect operations by keyword, including unloaded domains. It distinguishes itself from the many sibling tools by serving as a discovery mechanism, and specifies the return value (tool names, domain, 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 clearly implies when to use this tool: when you need to find the right operation by keyword, especially across domains not currently loaded. It provides explicit guidance on using English keywords and translating goals, but does not explicitly state 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 declare readOnly, idempotent, and non-destructive behavior. The description adds useful behavioral context about the return format (aggregated time-series, not individual records) and the endpoint. Given the strong annotation coverage, 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?
Two concise sentences with no fluff. The first sentence states the purpose, the second clarifies the output shape and includes the endpoint. Every word 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?
For a simple read-only metrics tool with strong schema and annotations, the description covers the key contextual points: what it does, the return type, and the endpoint. It does not need to explain defaults or optional parameters since the schema provides these.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and all parameters have clear descriptions, so the schema does the heavy lifting. The description does not add syntax or format details beyond what the schema already provides, which is acceptable but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'beta tester usages metrics for a beta group', and the scope 'aggregated time-series data, not individual records'. This distinguishes it from sibling tools like beta_testers__beta_tester_usages__metrics and builds__beta_build_usages__metrics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context that this tool is for aggregated group-level metrics and explicitly notes it does not return individual records, which implies when not to use it. However, it does not explicitly name alternative tools for individual-level metrics, so it falls short of full alternative 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, so the description's burden is lower. It adds value by specifying the default sort order ('newest first with sort=-uploadedDate'), summarizing filtering options, and indicating the HTTP method. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences front-load the purpose and key behavior (cross-app, default sort, filters), then provides the alternative usage. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 19 parameters and no output schema, the description is somewhat minimal. It lacks guidance on important usage patterns like pagination (next_url), relationship inclusion (include parameter to save API calls), and the fact that the response is a paginated list. While schema descriptions cover individual parameters, the overall context for an LLM to use the tool efficiently is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description mentions 'Filter by app, version or processing state,' which summarizes some filters but does not add meaning beyond the schema's parameter descriptions. No novel semantic information 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 explicitly states what the tool does: 'List uploaded builds across all apps, newest first with sort=-uploadedDate.' It clearly identifies the resource (builds) and the action (list), and distinguishes itself from the sibling tool apps__builds__list by specifying cross-app scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool versus the alternative: 'For one app's builds use apps__builds__list instead.' This directly tells the agent which tool to select based on the query scope, fulfilling the highest standard for this dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnlyHint=true, and the description adds valuable behavioral detail: it will not decide which languages need updating, output is a draft for human review, and keyword results are non-final starting points. This goes well beyond the annotation without contradicting it.
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, each carrying a distinct piece of information, and the core action is front-loaded. It is appropriately compact, though the phrase 'instruction for you to draft it' vs 'returns a draft' adds a slight ambiguity that keeps it from a perfect conciseness score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description tells the agent what to expect (source text plus instruction, and a draft for a person to read) and what not to do (write, infer locales, treat keywords as final). The parameter schema covers the remaining details, making the definition complete for an AI agent deciding to call 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%, so the baseline is 3, but the description adds meaning for fields like 'keywords' by explaining that a keyword draft is a starting point, not a finalized answer. It also reinforces the to_locales constraint that translation only happens for explicitly requested locales.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a specific deliverable (source store text plus drafting instruction), defines the action as drafting, and distances itself from applying changes or auditing staleness. This clearly separates it from siblings like metadata_ai__apply_localizations and metadata_ai__audit_localizations.
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 gives explicit context for when the tool should be used: only for locales the caller requests, never for the tool to infer stale languages, and as a human-readable draft rather than a committed write. It does not name exact alternative tools, but the exclusions are clear enough to route an agent.
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 readOnlyHint annotation is reinforced and extended by the description's explicit 'Read-only — it changes nothing and does not submit,' which adds the meaningful distinction that this tool will not trigger a submission. It also discloses the behavioral contract: it reports gaps, names the tool that fixes each gap, and inspects multiple areas of app metadata. The description fully describes what the tool does and guarantees beyond the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is detailed but every sentence earns its place: the lead sentence states the core purpose, the middle enumerates what is verified, and the closing sentences establish behavioral guarantees and output shape. It is slightly longer than strictly necessary — the enumeration of checks could arguably live in the output schema — but the structure is front-loaded and logical.
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 composite preflight tool with an output schema present, the description is complete: it explains what the tool does, how to identify the target app, what criteria are checked, that the result is a gap list with remediation pointers, and that it is side-effect-free. The presence of the output schema relieves the description of explaining return values. Nothing critical is missing for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters well. The description adds modest value by restating the app identifier formats ('name, bundle ID or Apple ID'), which matches the schema's app description, and confirms the version parameter's default behavior is schema-documented. With full schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource ('Check whether an app version is complete enough to submit') and clearly distinguishes the tool from the many sibling mutation tools, especially release__submit, by framing this as a non-submitting verification. It goes further to enumerate exactly which criteria are checked, so an agent knows precisely what the tool covers without opening the schema.
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 the clear usage scenario — run this before submitting a version — and the phrase 'does not submit' implicitly routes the agent away from release__submit. It does not name the sibling alternative explicitly or state when-not-to-use, but the read-only framing and the 'each gap names the tool that fixes it' behavior give sufficient contextual guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description redundantly states 'Read-only', adding no contradiction. The description adds valuable context by stating the trend is 'computed deterministically' and includes an instruction for summarization. It does not disclose further limitations, but with annotations covering safety, 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?
Two concise sentences, front-loaded with the primary action, followed by the summarization instruction and read-only note. Every clause adds value; 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 presence of an output schema and full parameter docs, the description covers the tool's functionality and even tells the agent how to use the result. The deterministic computation note prevents ambiguity about the trend calculation. It is complete for an agent to decide when and how to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of parameters, providing definitions for app_id and days, so the baseline is 3. The description's 'last N days' echoes the days parameter without adding syntax or format details. No additional parameter-level meaning beyond the schema 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 explicitly states the tool fetches reviews for an app over a lookback window with volume and rating trend, and instructs the agent to produce a summary. This is a specific verb-resource pair with clear scope, distinguishing it from generic review listing tools. The 'Read-only' tag reinforces its 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?
The description clearly implies the use case: generating a daily briefing from recent reviews, with a directive to summarize. It does not explicitly name alternatives or exclusion criteria, but the context is unambiguous. Given the rich sibling list including reviews_ai__triage and drafts, a direct comparison would have earned a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish this is a non-read-only, non-destructive, idempotent write, and the description does not contradict them. The description adds meaningful behavioral context beyond the annotations: the rating is computed from the answers rather than directly selected, which is a non-obvious trait that affects how the request must be constructed. It does not disclose partial-update semantics or whether omitted questions are left unchanged, so it falls short of a 5.
Agents need to know what a tool does to the world before 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 tight sentences with zero filler. The core purpose is front-loaded, the content-category examples are illustrative without being exhaustive, and the HTTP method/path suffix adds useful protocol context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a highly complex tool (nested JSON:API body with roughly 30 content-category attributes), the schema fully documents every attribute with enums and nullability, and the id parameter description directs the agent to 'the matching list call.' The description supplies the one framing the schema cannot — the answers-to-questions model and the derived-rating constraint. With no output schema, the response shape is left unspecified, but for a standard PATCH update this is a minor gap.
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% — both top-level parameters (id, body) have schema descriptions, establishing a baseline of 3. The description adds framing value on top: it signals that the body's numerous attributes are Apple's content questions, and the 'derived rather than chosen' note prevents an agent from hunting for a nonexistent direct-rating field. This meta-guidance justifies a score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('set the app's age rating') and a distinctive mechanism ('Answer Apple's content questions'). Listing concrete content areas (violence, gambling, mature themes, unrestricted web access) makes the scope unmistakable, and the 'derived rather than chosen' clause differentiates this from any tool that would set a rating value directly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use this tool: when the app's age rating needs to be set, you answer Apple's content questions. The 'derived rather than chosen' sentence acts as implicit usage guidance, steering the agent to populate content-category attributes instead of a rating field. It stops short of naming alternatives (e.g., app_infos__age_rating_declaration__get for reading) or explicit when-not-to-use conditions.
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 only claim non-read-only, non-idempotent, non-destructive, which is minimal. The description adds genuinely valuable behavioral context: ONE_TIME_SNAPSHOT covers the past 365 days, ONGOING accumulates continuously, and a fresh request has no instances for a day or more. This latency disclosure is exactly the non-obvious trait an agent must know to avoid expecting immediate results. 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, each earning its place: purpose, mode semantics, and latency expectation. The action is front-loaded, the mode explanation is compact, and no words are wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter create call with nested body and no output schema, the description covers the domain, mode selection, and the key behavioral surprise (the wait). The only gap is that it doesn't mention the response shape — i.e., that a created request resource/ID is returned for follow-up GET/delete calls — which the agent must infer from the POST endpoint pattern.
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), but the description adds real meaning beyond the schema by explaining what each accessType enum value does — ONE_TIME_SNAPSHOT = past 365 days, ONGOING = keeps going as new data arrives — which the schema merely lists. The app relationship is left to schema structure, but the critical decision parameter is semantically enriched.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Ask Apple to start producing analytics for an app', with the endpoint POST /v1/analyticsReportRequests appended. The scope of the data (downloads, sessions, retention, crashes) is explicit. The 'start producing' framing clearly distinguishes this creation action from sibling get/list/delete/reports tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful invocation context by explaining the two access modes (ONE_TIME_SNAPSHOT vs ONGOING) and the delay before data exists. However, it never explicitly routes the agent between this tool and its alternatives — e.g., that checking status should go to analytics_report_requests__get or that removal is analytics_report_requests__delete. Usage context is clear, but when/when-not guidance is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds valuable context beyond annotations: the URL is short-lived, the rows are gzipped TSV at that URL, and the response carries the link, not the data. This sets clear expectations about expiration and data format 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 two sentences, front-loaded with the core action 'Read one segment' and immediately clarifies the key caveat about the URL carrying the link, not the data. No unnecessary words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
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, the description covers the essential return value (short-lived signed URL, checksum, byte size), explains the data format (gzipped TSV at the URL), and clarifies the response does not contain the data itself. The absence of an output schema is compensated by this description, and the tool's low complexity means no further context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema: id says 'ID from the matching list call' and fields_analyticsReportSegments lists the enum with a warning about row size. The description reinforces that the attributes are checksum, sizeInBytes, and URL, but adds no new syntax or format details. With schema description coverage at 100%, the description does not need to compensate, so a 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 uses the specific verb 'Read' and names the resource 'one segment', clearly distinguishing it from list operations. It further clarifies that the response contains a short-lived signed URL, checksum, and byte size, not the actual data. This makes the tool's purpose unmistakable even among many sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies usage for fetching a single segment by ID, and the schema notes the ID comes from a matching list call. However, it does not explicitly name alternative tools (e.g., analytics_report_instances__segments__list) or provide when-not-to-use advice. 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?
Beyond the annotations (readOnly=false, idempotent=false), the description adds behavioral context: the experiment can have up to three treatments, traffic is split by share, and treatments must be attached separately. This clarifies what the tool does and does not do, which is valuable for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action and resource, and includes the endpoint path for clarity. Every sentence adds value with no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with a nested JSON:API body, the description captures the essential context: the purpose (A/B test), constraints (max three treatments, traffic split), and a clear boundary (treatments attached separately). The schema covers the parameter structure, so the description complements it well. Minor omissions like authentication or prerequisites are not critical here.
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 lists attributes (name, platform, trafficProportion) but provides no descriptions for them. The description adds meaning by explaining 'split by traffic share' (mapping to trafficProportion) and 'up to three treatments' (context for the experiment structure). This goes beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Start an A/B test') and clearly identifies the resource ('a version's product page'). It distinguishes itself from sibling tools by specifying the creation action and mentioning 'Treatments and their assets are attached separately', which sets boundaries against treatment-specific 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 clearly implies this tool is for creating experiments ('Start an A/B test'), and the note about treatments being attached separately guides users toward subsequent steps. However, it does not explicitly name alternative sibling tools for update/delete/get, though the context makes them obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: it discloses that the output varies by mode, listing profiles, sub-profiles, loaded status, tool counts, or tool domains. This goes beyond the annotation's simple read-only flag and helps the agent predict behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words. The first sentence packs the core functionality and mode distinctions, while the second gives a clear usage trigger. Each phrase earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simple no-parameter interface and the readOnlyHint annotation, the description covers the key use cases and output types (profiles vs. domains) sufficiently. It could be slightly more explicit about what 'tool domains' means or how the results are formatted, but it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description appropriately does not invent any. Since the input schema is empty and schema coverage is 100%, the baseline is 4; the description's explanation of profile mode and tool domains compensates for any possible ambiguity about what the tool returns.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships 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 'List' and clearly specifies the resource as 'what this server can reach and what it cannot', with distinct modes for profiles vs. tool domains. It distinguishes itself from the many CRUD sibling tools and implies a discovery function separate from asc__search_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 explicitly states 'Use this when a capability you need is not in the tool list', which provides a clear condition for when to invoke the tool. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks the full 'when/when-not/alternatives' 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?
The annotations (readOnly=false, idempotent=true, destructive=false) are not contradicted by the description. The description adds behavioral context by noting the operation is tester-facing and limited to one language, which is useful beyond annotations. However, it does not mention edge cases such as behavior when whatsNew is null 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 that includes the HTTP method, resource, and specific action, with no redundant words. It is front-loaded with the verb and resource, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple scope (updating a single field), a detailed input schema with nested objects, and annotations covering safety. The description conveys the primary intent adequately; while it does not explain the response format, the lack of an output schema and the simplicity of the operation make this acceptable.
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 already describes the top-level parameters (id and body), but the description adds semantic meaning to the nested 'whatsNew' field by calling it 'what to test' notes. This provides value beyond the schema's type-only definition and helps the agent understand the purpose of the field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Set' and clearly identifies the resource as the tester-facing 'what to test' notes for a TestFlight build, scoped to one language. It distinguishes from sibling create/delete tools by implying an update to an existing localization, further reinforced by the PATCH 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 provides clear context that this is for updating an existing localization's notes, but it does not explicitly mention alternatives like beta_build_localizations__create for new localizations. The verb 'Set' and the PATCH endpoint imply an existing resource, making the usage context clear but not explicitly excluding other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and delivers the two most operationally critical behaviors: pre-flight validation against Apple's character limits making a bad file change nothing at all, and the non-atomic per-language submission where a mid-way rejection still leaves earlier writes in place with errors naming exactly which ones landed. An agent needs both facts to set user expectations and interpret failures.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences with no wasted words, front-loaded with the core purpose and then covering formats, validation safety, and failure semantics in order of importance. Every sentence carries a distinct, decision-relevant piece of 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?
There is no output schema, so the description is the sole carrier of result semantics. It covers input formats, the all-or-nothing validation guarantee, and the partial-failure error behavior. It stops just short of describing the success-return shape, but the essential operational behaviors an agent needs are present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reiterates the CSV/JSON file formats in prose, but the schema's file_path description already documents the CSV columns and JSON structure, so the description adds no meaningful parameter-level semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Write store text for several languages at once from a file the user prepared.' This clearly distinguishes it from the sibling metadata_ai tools (audit_localizations, draft_translation) by emphasizing that values come from the user's prepared file rather than being generated or checked.
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 establishes the use case well: apply pre-existing user-provided file values in bulk, with the contrast 'rather than retyped' signaling when this tool fits. However, it never explicitly names alternatives like metadata_ai__draft_translation for generating text or app_store_version_localizations__update for a single manual edit, nor states 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 readOnlyHint=false and idempotentHint=false, so the description is not responsible for disclosing mutation. The description adds value by noting that the tool 'resolves the app, subscription and Apple price point internally' and 'performs the one write', which clarifies it performs a single atomic write rather than requiring multiple steps. It also mentions that if the price point does not exist, nearest prices are suggested (in the schema), but the description itself doesn't cover that. However, it doesn't disclose potential side effects on existing subscribers beyond the schema's preserve_current_price parameter. Overall, it adds useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and contains no filler. The first sentence clearly states what it does; the second gives a usage recommendation. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 6 params and no output schema, the description covers the core inputs and behavior well: it lists the necessary inputs, notes internal resolution, and gives explicit usage guidance. It does not mention the optional start_date or what the response contains, but the schema covers start_date and the tool is straightforward enough that these are not critical gaps. A 4 reflects that it is nearly complete but could briefly mention the return or the existence of the start_date parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description repeats parameter clarifications already present in the schema (app can be name/bundle ID/Apple ID, price format, territory code example) but does not add significant new semantics. It omits start_date and preserve_current_price from the description, though these are well-documented in the schema. Since the schema already explains each parameter thoroughly, the description neither hurts nor greatly helps here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Change or set'), a clear resource ('subscription price'), and scope ('in one territory (country) in a single step'). It also distinguishes the tool from the sibling read operation by emphasizing 'one write' and by referencing the alternative of chaining apps__list / subscription_groups / price_points calls. This is far beyond a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use this tool: 'Use this instead of chaining apps__list / subscription_groups / price_points calls when the goal is simply "set/raise/lower the price".' It also provides context that it resolves app, subscription, and price point internally, which helps the agent choose it over manual chaining. No exclusions are stated, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety profile is clear. The description adds useful context by specifying it fetches a single resource by ID and pointing to the GET endpoint. It doesn't disclose return format, but no output schema exists and the tool is simple.
Agents need to know what a tool does to the world before 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 one concise sentence with the endpoint, and the parameter descriptions are tightly written with no fluff. Everything earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID operation with full schema coverage and clear safety annotations, the description is complete. The ID source hint and include parameter cost guidance add valuable context. Could mention that it returns a single review submission resource, but that's already implied by 'Read one review submission by ID' and the 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?
Schema coverage is 100% with descriptions for all three parameters. The description adds an important hint on where to get the ID ('from the matching list call') and clarifies how the include parameter affects API calls, going beyond the schema's base 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 uses a specific verb ('Read') and resource ('one review submission by ID'), clearly distinguishing it from sibling list/create/update/delete review submission tools. The API endpoint is also provided for absolute clarity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates this tool is for reading a single review submission by ID, implying it should be used when the ID is known, as opposed to listing or creating. It doesn't explicitly name alternatives, but siblings make the contrast obvious. The 'ID from the matching list call' parameter description adds practical 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 write, idempotent, and destructive behavior, so the description adds context by explaining what 'submitted' and 'canceled' do and that this is a RELEASE-level write. It also clarifies the workflow distinction about starting the queue. It doesn't detail irreversible consequences or response details, but it meaningfully 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 two concise sentences, front-loaded with the primary action, and includes the endpoint and risk level. Every sentence adds meaningful information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-transition update with no output schema, the description covers what the tool does, when to use it, and the queue-starting behavior. It could mention response behavior or edge cases, but the annotations and schema fill most remaining gaps, making it complete enough for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by mapping the boolean attributes to concrete actions ('setting submitted to true' vs 'canceled'), which the schema does not explain. The id parameter is already documented as 'ID from the matching list call,' so the description enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb phrase 'Hand an open submission to Apple' and clearly explains the two primary actions (set submitted=true or canceled=true). It distinguishes itself from related operations by noting 'opening the submission and filling it does not' start the queue, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: it is the step that starts the queue, implying it should be used after opening/filling a submission. It also offers the alternative of canceling via 'canceled'. However, it does not explicitly name sibling tools or state when to prefer them, so the guidance is strong but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/destructive annotations (which already indicate safety), the description adds valuable behavioral context: it requires specific authentication roles, returns data as gzipped TSV, and explains the parse=true option to decode the blob into rows. It also notes the raw response behavior. 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?
Three concise sentences pack the essential information: purpose, output format, auth prerequisites, endpoint, and the key parse option. No filler or redundant details; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description combined with the rich schema covers the core operational details: what the tool does, required auth, output format, and the decoding option. Pagination via next_url is documented in the schema. It doesn't cover potential edge cases like rate limits or error handling, but for a read-only report downloader, the information is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides complete descriptions for all 9 parameters (100% coverage), so the description doesn't need to elaborate. It does reinforce the parse and max_rows semantics, but adds little beyond the schema. The baseline of 3 is appropriate given the strong 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 begins with a specific verb 'Download' and clearly identifies the resource as 'a sales or subscription report as gzipped TSV', which is distinct enough from sibling finance report tools. The included endpoint '[GET /v1/salesReports]' further pinpoints the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states prerequisites (ASC_VENDOR_NUMBER and Finance/Sales role) and provides the context for when to use it (downloading sales/subscription reports). However, it does not explicitly name alternative sibling tools like finance_reports__list or state when not to use this tool, so it misses the 'alternatives' component.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and idempotentHit already present, the description adds valuable multi-step context: walking the full request→report→instance→segment chain, downloading a gzipped TSV, and decoding rows. It also clarifies there is no side effect of starting a new request. This goes beyond the annotations and gives the agent a richer mental model, though it omits details like error conditions or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and efficiently written. It front-loads the main purpose, then immediately addresses the key alternative, and closes with a critical non-side-effect statement. Every sentence earns its place, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's multi-step nature, the description provides sufficient context: the chain traversal, the download/decode, the alternative listing mode, and the no-new-request constraint. The rich input schema and presence of an output schema cover parameter details and return shape, so the description completes the picture for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with rich descriptions for all six parameters. The description adds a high-level summary of which parameters matter ('app... and the report name or category') and clarifies that omitting 'report' triggers a list behavior, but these are already implied or stated in the schema. The additional value is marginal, warranting the baseline score 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 opens with a specific verb ('Read'), a clear resource ('App Store analytics report'), and the outcome ('returns decoded rows'). It distinguishes itself from the chained sibling tools by explaining the alternative approach and why this one is preferable, making its unique purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative tools (analytics_report_requests, analytics_reports, analytics_report_instances, analytics_report_segments) and explains they end with a URL rather than data. It also adds a conditional usage ('Omit to list what this app has available instead of downloading one') and explicitly states a non-goal ('Does not start a new report request'), giving clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnlyHint, idempotentHint, and non-destructive behavior. The description adds value by referencing the API endpoint '[GET /v1/appEncryptionDeclarations]' and implying pagination support via the 'next_url' parameter, which is not directly declared in annotations. There is 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 two sentences long, efficient, and front-loaded with the main purpose. It conveys necessary context without fluff. Minor deduction for not being as terse as possible (e.g., the endpoint notation could be integrated more elegantly), but it remains well-structured for an agent.
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 7 parameters, no output schema, and moderate complexity, the description covers essential aspects: purpose, typical use case (checking coverage before shipping), filtering guidance, and the endpoint. It does not need to explain return values since there is no output schema, and the parameter schemas already handle most details. The description is complete enough for an agent to decide and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. However, the description adds significant meaning beyond the schema: it explains that filtering by app or build helps check if a declaration covers a build, provides a real-world use case for 'filter_app' and 'filter_builds' parameters, and clarifies that you should use the Apple ID (not bundle ID) for filtering by app. This extra semantic guidance is essential for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List export-compliance declarations' providing a specific verb and resource. It distinguishes this tool from siblings by explaining its purpose: finding declarations that cover a build before shipping, which is a unique concern not shared by other sibling tools like builds__app_encryption_declaration__get or apps__app_encryption_declarations__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 says 'Filter by app or build to find whether one already covers the build you are releasing,' providing clear context for when to use it. It implicitly guides the agent to filter against an existing app or build to check coverage, but it does not explicitly state when not to use it or name alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds useful context that the deletion also removes 'its results,' and notes the update alternative. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the action, the second gives a conditional alternative. It is front-loaded, concise, and free of any redundant 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 one-parameter delete operation with no output schema, the description covers the action, the scope (including results), and the alternative path. It is fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% coverage with a single parameter described as 'ID from the matching list call.' The description adds no additional parameter detail, but the schema is sufficient, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Delete a product page experiment and its results' – a specific verb and resource. It also distinguishes itself from the update tool by mentioning the alternative, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly provides a when-not-to-use instruction: 'Halt it with an update instead if you still want the numbers.' This clearly signals the alternative tool and the decision boundary, which is excellent 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 provide readOnlyHint, idempotentHint, and destructiveHint. The description adds meaningful behavioral context beyond those by explaining the real-world consequence—loss of access to every build and group—and clarifying the difference from group-only removal. It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences carry all necessary information: the action and consequence first, then the exclusion of the related use case, and finally the endpoint. No filler or redundant restating of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter delete operation with annotations covering safety profile, the description fully equips the agent. It defines the scope, consequence, distinction from similar operations, and references the endpoint. No output schema exists, but none is needed for a delete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema covers 100% of parameters, and the 'id' field already includes a useful description ('ID from the matching list call.'). The tool description adds no additional parameter-level guidance, so the 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 states a specific verb ('Remove'), a specific resource ('a TestFlight tester'), and the exact scope ('from your account entirely... lose access to every build and group'). It also explicitly contrasts this with removing from a single group, making it immediately distinguishable from related sibling tools like beta_groups__beta_testers__remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates when to use this tool: when the tester should be removed entirely from the account. It also explicitly states a when-not case: 'Removing them from one group is a different call,' steering agents away from using this for group-level removal.
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 the description reinforces that with 'Read-only.' More importantly, it discloses behavior beyond the annotation: the one-call locale-by-locale comparison, the default version selection, the specific list of fields compared (description, keywords, whatsNew, promotional text, marketing URL, support URL), and the reporting of added/dropped locales. This gives an agent a clear picture of what the operation is doing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: it leads with the core purpose, then gives the necessary app-identification instruction, then explains default behavior, and finally the exact output scope. Every sentence earns its place; the 'what am I about to change?' framing adds practical orientation without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, default comparison versions, required app identifier, per-locale reporting, and the exact set of fields checked. With a rich output schema already present and a read-only annotation, nothing essential is missing for an agent to select and invoke 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 100%, so the baseline is 3, but the description adds meaningful value by specifying that 'app' can be a name, bundle ID, or Apple ID—details not present in the schema. It also reinforces the default from/to behavior, which aligns with and supplements the parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Compare the store text of two app versions') and clearly delimits the result ('list only what differs'). It names the exact resource (store text of two app versions, locale by locale) and distinguishes itself from siblings like listing__get_screenshots or metadata_ai__audit_localizations by focusing on a diff of metadata fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives strong contextual guidance: it explains the default comparison between the version on sale and the version being prepared, framing it as 'what am I about to change?'. It does not explicitly name alternatives or exclusion criteria, but the use case is clear enough that an agent can decide when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds behavioral context beyond that: it reveals the one-step nature and exactly what information is returned (locales, device sizes, counts, dimensions), and it explains the efficiency rationale. It does not go into pagination or error cases, but the presence of an output schema lowers that burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the core purpose, the output scope, the required input, and an explicit comparison to a more expensive alternative. Every clause earns its place—no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool’s complexity is moderate, but the description covers the key purpose, the output highlights, and the recommended usage context. Since an output schema exists, the description does not need to spell out return fields, and the efficiency warning about chaining calls is valuable contextual guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with clear descriptions for app, locale, and version. The description’s mention of 'Give the app' and the 'one step' optimization does not add meaningful parameter semantics beyond what the schema already provides, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb ('List') and a clear resource ('screenshots on an app’s store listing'), then enumerates what the result includes (locales, device sizes, counts, dimensions). It also distinguishes itself from the manual multi-call chain (app_store_versions / localizations / screenshot_sets / screenshots), making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Use this instead of chaining app_store_versions / localizations / screenshot_sets / screenshots' and explains why (most locales carry no screenshots, so the chain is costly). It also tells the caller what input to provide ('Give the app (name, bundle ID or Apple ID)'), leaving no ambiguity about when to invoke 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?
The description adds valuable behavioral context beyond the readOnlyHint annotation: it states 'Returns data only — never posts' and 'you write the text,' clarifying that the tool does not automatically publish. It also mentions 'no separate API key needed,' an important authentication detail. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, front-loaded with the core purpose, followed by safety and workflow notes. Every sentence earns its place without unnecessary detail or repetition.
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 output schema and readOnlyHint annotation, the description is complete. It explains the full workflow: fetch a review, receive drafting instructions, review the draft, and post via a companion tool. It identifies the specific post tool (`customer_review_responses__create`) and clarifies safety, leaving no critical gaps for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear descriptions for both `review_id` and `tone`. The tool description does not add additional parameter-specific meaning beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: 'Fetch one customer review and return it with an instruction for you to draft a reply.' It also distinguishes itself from the posting tool by saying 'Returns data only — never posts' and references `customer_review_responses__create` for posting, making its purpose distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit workflow guidance: draft a reply with this tool, then 'post it yourself with customer_review_responses__create if you approve it.' It also notes 'no separate API key needed,' which is a usage condition. However, it does not explicitly name alternatives for merely fetching a review (e.g., `customer_reviews__get`), though the intended use case 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?
Even though annotations already mark readOnlyHint=false, the description adds valuable behavioral context: it 'handles Apple’s reserve/upload/commit sequence and the checksum,' and discloses that it's a 'PUBLIC-level write' where the image appears after Apple processes it. This goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, input summary, and behavioral caveat. It is front-loaded and packs essential information without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explains the full work flow, including the hidden sequence, the fact that it's a public write, and that Apple processes asynchronously. This is sufficient for an agent to understand the tool's scope and effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description maps user-facing concepts (app, locale, device size, file path) to parameters but adds no new meaning beyond what the schema already provides. Version is not mentioned but is optional and already described in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Upload a screenshot image file to an app’s store listing in one step.' It distinguishes itself from the raw screenshot tool by explicitly noting that the raw tool 'reserves a slot and moves no bytes,' clarifying exactly what this tool does differently.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear guidance by contrasting with the raw screenshot tool: 'the raw screenshot tool reserves a slot and moves no bytes.' This implies you should use this tool when you actually want to upload file bytes, making the when-to-use decision 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?
Adds valuable behavioral context beyond annotations: clarifies that the call does not send anything, opens an empty submission, and is a release-level write. It does not contradict the destructiveHint annotation, though it could elaborate on potential side effects of creating the submission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with the main purpose in the first phrase. Every sentence adds useful information: the step context, what it does not do, and the next actions. The endpoint is included without clutter.
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 lack of an output schema, the description sufficiently covers what the agent needs to know: the tool's role in the three-step process, what it creates, and what to do next. It integrates well with the sibling tool names and schema requirements.
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 only describes the body generically as 'JSON:API request body.' The description adds meaning by explaining that this call creates an empty submission and that the version is not set here, which helps the agent understand that the body should contain only the app relationship.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a review submission but is only step 1 of 3 and does not actually submit anything. It explicitly says it 'opens an empty submission for an app,' which distinguishes it from the actual submission step and from sibling tools like review_submissions__update.
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?
Directly provides a step-by-step workflow: 'step 1 of 3,' followed by instructions to use review_submission_items__create and then set submitted. This gives explicit guidance on when to use this tool and what to do next, with a named alternative for the subsequent action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds valuable behavioral details beyond annotations: worldwide pricing is 'grouped by price so the answer stays readable, with the currency and the country codes in each group,' and it 'returns the price actually in effect' unlike subscriptions__prices__list which returns 'price-less stubs.' This discloses output formatting and a common pitfall.
Agents need to know what a tool does to the world before 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 and is front-loaded with the core purpose. The description is dense but not verbose: it covers purpose, parameter behavior, alternative usage, and a caveat about subscriptions__prices__list in just four sentences. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only getter, the description fully covers all usage scenarios, optional parameter behaviors, alternatives, and a key caveat about the alternative API. The output schema exists, so return values need not be described in detail. The description is complete for an agent to select and invoke 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?
The schema coverage is 100%, and the description reinforces parameter meanings with additional context: app can be name, bundle ID, or Apple ID (also in schema); omitting territory gives worldwide pricing 'grouped by price'; omitting subscription covers all subscriptions and enables answering price questions without product ID. The description adds usage nuance beyond the schema, though the schema already covers the basics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear statement of what the tool does: 'What a subscription costs customers today — in one country, or in every country at once.' It specifies the resource (subscription price) and scope (by country or worldwide), and the verb 'get' is implied in the name and description. It distinguishes itself from sibling tools like pricing__set_subscription_price and pricing__equalize_price 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 Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use this tool: 'Use this instead of chaining apps__list / subscription_groups / prices calls.' It also explains when to include or omit each optional parameter, giving concrete scenarios like answering 'what does the weekly one cost' without knowing the product ID. This provides clear usage guidance relative to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It clearly discloses that the tool performs multiple internal steps, checks submittability first, and refuses to submit versions that would bounce. The skip_preflight parameter description adds further 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?
Three tightly written sentences, front-loaded with the core action and followed by meaningful caveats and alternative routing. No wasted words or redundant schema repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for an action tool of this complexity: it explains the workflow, the safety check, the refusal behavior, and the alternative. The presence of a full output schema means return values do not need to be described in prose.
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 already documents all parameters at 100% coverage. The description adds value by explaining the orchestration behavior and warning about skip_preflight, but the parameter-specific extra is modest beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear, specific action: send an App Store version to Apple for review in one call. It also distinguishes this tool from review_submissions__create, making the scope and purpose easy to identify.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use this tool instead of review_submissions__create, and explains why: that sibling 'by itself sends nothing.' It also notes the pre-flight behavior, reinforcing when this tool is the right choice.
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:

[![app-store-connect-mcp MCP server](https://glama.ai/mcp/servers/erayendes/app-store-connect-mcp/badges/card.svg)](https://glama.ai/mcp/servers/erayendes/app-store-connect-mcp)

Score Badge

Copy to your README.md:

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

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