Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explains non-destructive behavior (adding an app) and the expected post-add state ('Set up build' shown). Annotations are minimal, and the description adds useful behavioral context without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that front-loads the purpose. It is slightly verbose but every sentence provides useful information. Could be more concise, but structure is good.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, no output schema, and minimal annotations, the description covers parameter semantics and post-add expectations. It is complete enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 significant meaning to 'repository_url' by detailing HTTPS vs SSH behaviors. It does not expand on 'team_id' but the added value for the key parameter warrants a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'Add a new application to Codemagic by connecting a Git repository,' clearly specifying the action (add) and resource (application). It distinguishes from sibling tools like 'list_applications' or 'trigger_build'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides guidance on when to use HTTPS vs SSH URLs and mentions prerequisites (connected account for private HTTPS repos). It does not explicitly state when not to use the tool or name alternatives, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate it's not read-only or destructive. The description adds that the tester receives an invitation email from Apple, disclosing a side effect beyond the basic mutation. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the core purpose and immediately follow with optional usage and side effects. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, optional usage, and an important side effect. However, it does not specify the return value or behavior (e.g., if the tester already exists). Given no output schema, a brief note on expected response would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with descriptions. The description adds value by linking app_id to list_asc_apps and group to list_testflight_groups, aiding in correct parameter selection beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 (tester to TestFlight), and method (by email). It distinguishes from siblings like create_testflight_group by focusing on adding a tester to an existing group rather than creating groups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using list_testflight_groups to get group names, providing concrete context for when the optional group parameter is needed. It does not explicitly state when not to use this tool but offers sufficient guidance for proper invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate write operation (readOnlyHint: false) and non-destructive (destructiveHint: false). Description adds context about secrecy and that it's for non-secrets, aligning with annotations. Could mention if overwriting or error on duplicate name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with verb and resource, no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers main purpose, usage boundaries, and all required parameters. Does not specify behavior on duplicate variable name or if group doesn't exist, but for a simple add tool this is still sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage of parameters, so baseline is 3. Description does not add additional meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the verb 'Add' and the resource 'non-secret variable to a variable group'. Explicitly distinguishes from adding secret variables, focusing on the appropriate use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (non-secret variables) and when not to (secret values should use Codemagic UI). Provides clear guidance and safety warning.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true. The description adds that it has no effect on finished builds, providing additional behavioral nuance 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences with no wasted words. The primary purpose is front-loaded, and every sentence serves a clear purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the single parameter and lack of output schema, the description fully covers what the tool does, when to use it, and where the parameter comes from. It is 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the build_id parameter with 100% coverage. The description adds value by stating the source of the ID (from trigger_build or list_builds), which aids in parameter selection.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (cancel) and resource (a running or queued Codemagic build). It distinguishes itself from sibling tools like trigger_build and get_build by focusing on cancellation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides specific scenarios (wrong branch, error after triggering) and mentions no effect on finished builds. While it doesn't explicitly name alternatives, the context is clear enough for an agent to decide when to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description fully discloses behavior: API-verifiable checks run live, items without API are listed as 'human required', and each item is tagged as 'agent can fix' or 'human required'. No 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with front-loaded purpose, but slightly verbose. Each sentence adds value, but could be condensed slightly without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the return is a pass/fail report with action plan tags. It also references related tools (list_asc_apps). Missing exact output format but sufficient for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions. The description adds context (e.g., app_id from list_asc_apps, version example, language default) that goes beyond the schema, clarifying parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it aggregates publish-readiness checks for iOS or Android into a pass/fail report, distinguishing between API-verifiable and human-required items. This clearly defines the tool's specific function and differentiates it from sibling tools that may perform individual checks or actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to call before 'submit_for_app_store_review' (iOS) or promoting to production (Android), and refers to first_publish_ios/android prompts for initial setup. This provides clear when-to-use and preconditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses that the returned URL is accessible without authentication, time-limited, and anyone with the link can download. This adds valuable security context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the purpose and required input, then add context on security and use case. Every sentence is valuable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While no output schema is present, the description implicitly indicates a URL is returned. The use case and input are well covered. Slight gap: no explicit mention of output structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds context for artifact_url ('Pass the artifact URL...') but does not significantly enhance meaning beyond the schema. No further detail on expires_in_hours.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create a time-limited public download URL for a build artifact' and specifies the source of the artifact URL (get_build or wait_for_build). This distinguishes it from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use: pass the artifact URL from get_build or wait_for_build, and for sharing with testers without Codemagic access. It does not explicitly state when not to use, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is a write operation (readOnlyHint=false) and not destructive. The description adds critical behavioral context: external groups require beta app review before testers can install, while internal groups skip review. This goes 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences concisely deliver purpose and key behavior. The header immediately states the action, and the second sentence adds crucial operational nuance. No unnecessary words or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple creation tool with 3 basic parameters and no output schema, the description covers the essential context: what it does, the key distinction between internal/external, and the implication for testing workflow. No gaps remain.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed parameter descriptions. The tool description adds a note about review requirements that ties to the 'internal' parameter, but it mostly reinforces the schema definition. For app_id and name, no additional meaning is added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb+resource: 'Create a new TestFlight beta group for an app.' It clearly distinguishes from sibling tools like list_testflight_groups and add_testflight_tester, and explains the internal/external split, which further clarifies the tool's role.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use internal vs external groups (internal for fast QA without review, external requiring review). However, it does not explicitly mention when to avoid this tool or suggest alternatives (e.g., adding testers), leaving some guidance implicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-readonly and non-destructive, which matches the creation action. The description adds scoping constraints but no details on permissions, error states, 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is only two sentences, both essential: the first states purpose and prerequisites, the second gives post-creation guidance. No redundant or missing words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple creation tool with no output schema, the description covers the main scenario and next steps. It lacks details on validation behavior (e.g., if both team_id and app_id are provided) but is largely adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage for parameter descriptions. The description adds value by explaining the purpose of team_id vs app_id and the limitation for personal accounts, helping the agent choose correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool creates a new variable group in Codemagic, specifying team-level vs app-level groups. It distinguishes from sibling tools like add_variable, which adds variables to existing groups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on required parameters (team_id or app_id) and when each is appropriate (personal accounts cannot use team_id for global groups). It also directs the agent to use add_variable for non-secret variables after creation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds important behavioral context: 'Deletion is asynchronous — the API returns immediately and completes in the background.' This goes 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words. Front-loaded with the action and resource, efficiently covering both modes and async behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers the key behavioral aspect (async deletion) and parameter behavior. It is complete for a delete tool with two parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters documented. The description provides no additional meaning beyond the schema, except reinforcing the behavior for cache_id. Baseline 3 is appropriate as the schema already handles parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it deletes a build cache for a Codemagic app, and differentiates between deleting a specific cache (with cache_id) or all caches (when omitted). This distinguishes it from sibling tools like delete_variable or delete_webhook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the two usage modes (specific cache vs all caches) but does not explicitly state when to use this tool versus alternatives or provide any when-not guidance. Usage is implied by the parameter behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by stating 'This cannot be undone', reinforcing the destructiveHint=true annotation. It also explains the source of the variable_id. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundant information, front-loaded with purpose. Every sentence is earned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (two required parameters, destructive, no output schema), the description is complete. It covers purpose, parameter sourcing, and irreversibility, which is sufficient for correct agent invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaning by indicating that variable_id is obtained from list_variable_groups, which provides sourcing context beyond the schema's description of 'The variable ID to delete'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Delete a variable from a Codemagic variable group' and identifies the resource (variable within a group). It distinguishes from sibling tools like list_variables or add_variable by specifying the verb 'Delete' and the context of variable groups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides a clear usage context by noting that the variable_id comes from list_variable_groups, implying a prerequisite. However, it does not explicitly state when to use this tool versus alternatives or when not to use it, which 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description aligns with the destructiveHint annotation but adds no additional behavioral context beyond the annotation. It does not disclose irreversibility, immediate effects, or any side effects, which would be valuable for a destructive operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using a single sentence that is front-loaded with the key action. It is efficient but could include a bit more detail without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple destructive tool with 2 parameters and no output schema, the description is somewhat complete. However, it lacks caveats about irreversibility or permission requirements, leaving some gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters having descriptions. The description adds no extra semantic value 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.

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 (webhook subscription), and the context (from a Codemagic app). It is specific and distinct from sibling tools like list_webhooks.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 such as listing webhooks first to obtain the webhook_id. The schema description for webhook_id references list_webhooks, but 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so description doesn't need to state safety. It adds value by describing return values and a usage tip, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two effective sentences, front-loaded with purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description lists return fields. Parameter usage is clear with actionable advice. Tool is simple and fully explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers both parameters with descriptions (100% coverage). Description adds practical guidance: file_paths should include at least two directory levels, and package_json_content helps detect React Native vs Ionic.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it detects Codemagic project type from repository file listing, specifies return values (template type, confidence, debug template), and no sibling tool duplicates this functionality.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly notes that providing package.json content improves accuracy for JS/TS projects, giving a clear when-to-use hint for that parameter. No explicit when-not, but no alternative tools exist, so context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. 'Fetch' implies read-only operation, but doesn't explicitly state no side effects or authentication requirements. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose and returns, second gives usage guideline. Extremely concise and front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description details return fields (title, short description, full description). Simple fetch operation, sufficiently complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% (both parameters described in schema). Description adds no additional meaning beyond schema for package_name and language. Baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Fetch the current Google Play store listing' and specifies returned fields (title, short description, full description). Distinguishes from iOS counterpart and sibling set tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use before set_android_store_listing to review existing text.' Provides clear context for when to use, though no explicit exclusion of alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully convey behavior. It indicates a read operation ('Get') and what data is included, which is sufficient for a non-destructive tool. However, it does not disclose potential side effects, authentication requirements, rate limits, or response structure, leaving gaps for an AI agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and scope. Every word adds value, and no extraneous information is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an output schema, the description provides a good overview of what the dashboard includes (build, TestFlight, App Store version, submission state). It is reasonably complete for a read-only tool, though it could mention error handling or format. The description is clear enough for most use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers the sole parameter app_id with a description, achieving 100% coverage. The description adds no further parameter details beyond the schema, so it meets the baseline of 3 without adding extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and clearly identifies the resource as 'full release pipeline status dashboard for an app'. It lists concrete components (latest build, TestFlight, App Store version, submission state) which distinguishes it from siblings like get_asc_review_status that focus on a single aspect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for obtaining a comprehensive release status, but it does not explicitly state when to use this tool over siblings (e.g., get_asc_review_status, get_build) nor provide exclusions or context about prerequisites. The guidance is reasonable but not explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. The description implies a read operation ('Get'), but does not explicitly state safety, idempotency, or any constraints such as required permissions or rate limits. For a simple get operation, this is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences. No unnecessary words. Every sentence adds value: first states purpose, second provides usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple get status tool with one parameter, the description is largely complete. No output schema exists, but the description says it returns 'status' implicitly. It does not describe the format of the response or possible values, but the tool's purpose is straightforward.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (app_id is described in the schema). The description does not add any parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool gets the current App Store review status for an app. The verb 'get' and resource 'App Store review status' are specific. Does not explicitly distinguish from sibling tool 'get_asc_release_status', but the name and description imply a difference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit context: 'Call this after submitting to the App Store to monitor progress and check for blockers.' This tells the agent when to use the tool. No exclusions or alternatives mentioned, but the usage context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. While it mentions auth token requirements for artifact URLs, it does not state whether the operation is read-only, has side effects, or any other safety information. The read-only nature is implied but not explicitly stated, which is a gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core purpose, followed by essential context. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is adequate but lacks specifics on the return structure beyond 'full details'. It covers the key points but could be more complete about what exactly is returned.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds value beyond the schema by specifying that the build_id comes from trigger_build or list_builds, giving the agent source context. Although the schema has 100% coverage, the description's additional guidance compensates for the schema's minimal description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Get full details for a single build including artifact download URLs', which is a specific verb-resource pair. It distinguishes itself from sibling tools like list_builds and get_build_logs by focusing on a single build with full details and download URLs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells the agent when to use this tool: after trigger_build or list_builds, and how to use the results (artifact URLs with specific tools). It provides clear context for proper invocation, though it does not explicitly mention when not to use it or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true, which the description matches. It adds behavioral details: 'by default returns logs for failed steps only' and 'Always returns the step list with statuses first', informing the agent about the response structure 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each earning its place: first states purpose, second explains default behavior and use case, third covers the optional parameter and return format. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and low complexity, the description adequately covers return behavior (step list first) and the two scenarios. It is complete enough for an agent to understand what the tool does and when to use it, though more explicit output structure details could improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are well-described in the schema. The description adds minimal extra meaning: it restates the schema's explanation for step_name very closely. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Fetch logs for a Codemagic build', clearly stating the verb and resource. It distinguishes from siblings like 'get_build' and 'get_test_results' by focusing on logs and specifying the default scope (failed steps).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states the primary use case ('diagnosing why a build failed') and explains how to fetch logs for a specific step using step_name. While it doesn't mention when not to use it or list alternatives, the context is sufficiently clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It is non-destructive and read-only, but no other behavioral traits are disclosed. Adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and returns, followed by usage guidance. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, return structure, and usage context. Could mention return format more, but sufficient for a simple read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions for both parameters. The description adds value by explaining the return structure and grouping by locale.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it pulls the current App Store listing text for all locales of an app version, listing specific fields returned. This distinguishes it from sibling tools like set_ios_store_listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using this tool before set_ios_store_listing to review live data, providing clear context for its use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Despite no annotations, the description clearly indicates a read-only operation (get) with no destructive actions, fully disclosing its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences with no filler; each sentence adds essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the tool simplicity is covered, the description does not explicitly state the return value format (e.g., integer). Otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds no new meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves the highest versionCode from Google Play, distinguishing it from siblings like 'get_build' or 'list_google_play_bundles'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises using it before a release build to determine the next BUILD_NUMBER by incrementing the result. Could mention alternatives 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses build must be terminal, artifact search behavior, skip logic with artifact_url, output summary structure (pass/fail/error/skip with failure details), and prerequisite of test_report glob. Lacks mention of error handling if no JUnit found, but broadly informative.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph of 5 sentences, front-loaded with main action. No wasted words, but could be more structured with line breaks for readability. Efficient but not maximally structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (no output schema), description covers input requirements, behavioral constraints (terminal state), output summary, platform scope, and prerequisite. Lacks details on exact output format or error cases, but is comprehensive enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining artifact_url's purpose (skip search, use from wait_for_build) and how it relates to the workflow. This goes beyond the schema's raw descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches and parses test results from a Codemagic build, specifying the verb (fetch, parse), resource (test results from build), and distinguishing it from sibling tools like get_build or get_build_logs by focusing on JUnit XML parsing. It covers multiple platforms and mentions optional artifact URL shortcut.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear when-to-use context: after build reaches terminal state, can use artifact_url from wait_for_build, requires codemagic.yaml with test_report glob. Does not explicitly exclude scenarios or compare to alternatives, but the information is sufficient for an agent to decide.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already show readOnlyHint=true; description adds no contradiction and explains the URL's purpose, but no extra behavioral traits like 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words: first states purpose, second gives usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Simple tool with single parameter and no output schema; description fully explains what the URL is used for, making it complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter app_id with full schema description; description adds no further detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool gets an incoming webhook URL for a Codemagic app, distinguishing it from sibling tools like list_webhooks, delete_webhook.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to paste the URL into Git provider settings for automatic build triggers, but does not mention when not to use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses important behaviors: templates only cover build/signing, Android default linux_x2, personal account restriction. Could mention output format but acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise at 2 sentences plus a caveat. Front-loaded with purpose. Could be slightly more structured but efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description covers purpose, scope, exceptions, and sibling tool. Complete enough for agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and already explains the parameter well. The tool description adds little 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.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets a starter codemagic.yaml template for a given project type, and specifies it covers build and signing only, differentiating it from publishing tools and sibling list_yaml_template_types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use (get template) and when not (publishing handled separately via App Store Connect tools), and advises to call list_yaml_template_types first. Provides platform-specific caveats for Android and personal accounts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. The word 'list' implies a read-only operation, but no explicit mention of safety (e.g., no destructive side effects) or authentication needs. It is adequate but lacks detail beyond the basic action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no extraneous information. Every sentence adds value: the first states the action, the second explains its importance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one optional parameter and no output schema, the description is complete. It explains the purpose, the role in the workflow, and the parameter. Could mention the return value (list of apps with IDs) but it's implied by the purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema describes the only parameter 'team_id' with full coverage. The description adds no additional 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.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists all applications and explicitly mentions its role as a prerequisite to get app IDs needed by other tools. The verb 'list' is specific and the resource 'applications' is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use it: 'Call this first to get the app IDs needed by all other Codemagic tools.' This provides clear guidance on its placement in workflows and distinguishes it from siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but the description accurately describes the read operation and the critical output (ASC app ID). Lacks detail on authentication or rate limits, but this is sufficient for a simple 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with no redundancy. Front-loaded with action and purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a parameterless list tool with no output schema. The description fully informs the agent of the tool's role and when to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description adds value by linking the output (ASC app ID) to the purpose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it lists apps in App Store Connect and explicitly identifies the primary purpose: getting the ASC app ID needed by other tools, distinguishing it from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to call this first, establishing it as a prerequisite for all other App Store Connect tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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 only mentions listing builds and a subsequent action, but fails to disclose any behavioral traits such as read-only nature, rate limits, pagination, or error conditions. The user is left to assume the tool is safe and returns all builds without 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that combines purpose and usage instructions. While concise, it tries to convey too many ideas at once, reducing clarity. A more structured format with separate purpose and usage sections would improve readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks important context such as the return value structure (list of builds with which fields?), error handling, and permissions needed. Since there is no output schema, the description should at least indicate what the tool returns. The mention of 'highest version number' hints at the output but is insufficient for a complete understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with a description for 'app_id'. The tool description adds no additional meaning beyond what the schema provides. Thus, it meets the baseline expectation but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it lists TestFlight builds for an app, but it mixes this with specific workflow instructions (find highest version, increment, pass to trigger_build). The core purpose is clear but muddled by additional operational guidance, and it does not differentiate from the sibling tool 'list_builds' which may also list builds.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage before triggering a release build, providing a specific scenario. However, it does not explicitly state when to use this tool versus alternatives like 'get_latest_build_number', 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses return of 'build IDs and status' and hints at list behavior, but omits common traits like pagination, ordering, or default sorting.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first defines purpose, second provides usage guidance. No wasted words, efficient structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters and no output schema, description adequately covers purpose and return summary. Lacks detail on pagination or limit behavior, but otherwise complete for a list tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. The tool description adds no extra meaning beyond 'optional filters', 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.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'List builds for a team with optional filters', specifying verb (List), resource (builds), and scope. Distinguishes from sibling get_build by directing users to get_build for full details.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use get_build instead of list_builds, providing clear context. Does not cover all alternatives (e.g., when to use other list tools) but sufficient for main distinction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations declare readOnlyHint=true, so the tool is safe. The description adds that caches are scoped to a workflow, which is behavioral context beyond the annotation. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The main action is front-loaded, and the structure is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one parameter and no output schema, the description provides enough context: it lists caches, scopes to a workflow, and mentions cache IDs for downstream use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with the app_id parameter fully described. The description does not add meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists build caches for a Codemagic app, specifying that each cache is scoped to a workflow. It distinguishes itself from sibling tools like delete_cache and other list tools by focusing on caches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using cache IDs with delete_cache to free storage or force clean builds, providing a clear use case. However, it does not explicitly mention when not to use this tool or compare it to other list tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It indicates the tool is read-only (list) and returns version codes, but does not disclose pagination behavior, rate limits, or what happens if no bundles exist. Adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no wasted words. First sentence defines function, second provides usage context. Perfectly concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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, no annotations), the description is sufficient to understand what it does and when to use it. It could mention the return format or potential performance implications, but overall complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning to the package_name parameter beyond what the schema already provides (e.g., format or constraints).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists uploaded App Bundles (AAB) with version codes, using a specific verb and resource. It distinguishes from siblings like upload_to_google_play and list_google_play_tracks by its focus on bundles, but does not explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises using this tool before triggering a new build to audit existing uploads, providing clear context. It does not mention when not to use or alternatives, but the usage guidance is sufficient for a list tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Reveals key behavioral traits: only text-containing reviews returned, pagination (pages of 100 fetched transparently), translation support, and inclusion of review IDs. With no annotations, the description adequately discloses behavior, though it could explicitly state that the tool is read-only or mention 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, tightly written with no redundancy. First sentence states purpose and key constraint, second gives usage advice, third connects to sibling, fourth notes ordering. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description covers input and behavioral details well but omits the structure of the returned reviews (e.g., fields like text, rating, date). For a list tool, the output structure is useful context. Adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and description adds significant value beyond schema descriptions: clarifies max_star_rating usage for negative reviews, explains max_results paging behavior, and mentions translation_language for non-English reviews. Package_name is straightforward but well-contextualized.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'List recent Google Play user reviews for an app' with specific verb and resource. Mentions that only text-containing reviews are returned, distinguishing from all reviews. Also connects to sibling tool reply_to_google_play_review by noting review IDs are included.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides practical advice on using max_star_rating to focus on negative reviews with an example. Notes ordering by last modified date. No explicit when-not-to-use or alternative comparisons needed since no direct sibling for same resource, but 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description implies a read-only operation but does not explicitly state it has no side effects, permissions needed, or rate limits. Adequate but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no unnecessary words. First sentence defines purpose, second gives workflow advice. Efficient but could separate purpose from usage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description does not explain return format or fields like 'release info'. For a simple list tool, it covers the basic workflow but lacks output details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear parameter description. The tool description adds no extra meaning beyond what the schema provides, so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists Google Play tracks with release info and version codes. It distinguishes from siblings like 'get_latest_build_number' and 'promote_google_play_release', though it includes secondary usage guidance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a specific use case (finding highest versionCode and setting BUILD_NUMBER) but does not explicitly state when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that the default returns two types, all=true returns full matrix, and it returns pixel dimensions. It does not mention rate limits or side effects, but for a read-only list operation 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences long, each sentence serves a purpose: stating the function, describing default behavior, and explaining usage. No fluff, front-loaded with purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 optional parameter, no output schema), the description is complete. It tells the agent what to expect (device types and dimensions) and how to use the output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description adds significant value: it explains the effect of all=true (full matrix) and the default behavior (two most-required types). This goes beyond the schema's brief description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists supported screenshot device types and their required pixel dimensions. It distinguishes itself from sibling tools by explicitly linking its output to the upload_ios_screenshots tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidance: use the returned deviceType values as the device_type parameter for upload_ios_screenshots. It also explains the default behavior and the all parameter. While it doesn't explicitly mention when not to use it, 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It doesn't disclose whether the operation is read-only, requires authentication, or any potential side effects. While listing teams is likely safe, the description lacks explicit behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short, purposeful sentences. No wasted words. The first sentence states the core purpose, the second provides essential usage guidance. Highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is mostly complete: it covers purpose and usage integration. However, it does not describe the return format (e.g., list of team objects with ID and name) nor any potential empty results. The lack of output schema is not compensated by a description of the output structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the schema is fully covered. No parameter semantics are needed, and the baseline score of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('teams the authenticated Codemagic account belongs to'). It distinguishes itself from sibling list tools by focusing on teams, and even explains the purpose of the returned data for use with other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The explicit instructions to use the returned team IDs with list_applications, list_builds, and other tools provide clear guidance on when to use this tool and how its output is applied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description indicates a read-only list operation but does not disclose details like pagination, ordering, or authentication requirements. For a simple list tool, this is minimally adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero redundancy. The first sentence states the action and resource, the second provides immediate utility context. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter list tool with no output schema, the description is complete: it tells what it does and how to use the results. Could mention if listing includes all groups regardless of status, but not essential.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with app_id described as 'The App Store Connect app ID'. The description adds minimal extra meaning by saying 'for an app', slightly reinforcing the parameter's purpose. Baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 'TestFlight beta groups for an app'. It distinguishes from sibling tools like create_testflight_group (creates groups) and upload_to_testflight (uses groups) by explicitly stating the output usage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: 'Use a group name from this list in the beta_group parameter of upload_to_testflight'. While it lacks when-not-to-use, the guidance is clear and practical for the tool's purpose.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses that secret values are never returned, implying read-only behavior and no side effects. For a simple listing tool, this is sufficient, though it could mention 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two well-structured sentences. First states purpose, second adds a critical usage note. No fluff, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description must compensate. It mentions group names are returned but doesn't describe the full output structure (e.g., array with IDs, names). Also doesn't clarify that both parameters are optional but at least one might be needed. Adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond repeating 'team or app'. Both parameters already have clear schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists variable groups for a team or app in Codemagic. It distinguishes from siblings like list_variables and create_variable_group by specifically mentioning groups and their use in trigger_build.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use the tool (to list variable groups) and hints at usage in trigger_build. It also warns that secrets are not returned, advising to use the UI for secrets. However, it doesn't explicitly contrast with other list tools or specify prerequisites like providing at least one parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. The description adds value by disclosing that secret variable values are returned as null, which is a critical behavioral trait not captured by annotations. This goes beyond mere read-only safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three sentences, front-loaded with the core purpose, followed by output details and usage guidance. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one parameter and no output schema, the description covers all necessary aspects: what it lists, the masking of secrets, and how to use the results. It is fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for group_id. The tool description does not add additional meaning beyond what the schema provides for parameters, so it meets the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists variables in a Codemagic variable group and specifies the output (IDs, names, values, with secrets as null). It distinguishes itself from sibling tools like add_variable, delete_variable, and update_variable by mentioning usage of variable IDs with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: it indicates where the group_id comes from (list_variable_groups) and suggests that the output IDs are used with update_variable and delete_variable. While it doesn't explicitly state when not to use it, the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotation readOnlyHint=true already indicates the tool is safe. The description adds that it lists existing subscriptions, which is consistent. However, it does not disclose any additional behavioral traits (e.g., pagination, ordering, or empty result behavior).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

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. Every word is necessary; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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, annotations present), the description is mostly complete. It lacks explicit mention of the return format, but for a list tool this is often implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema describes the single parameter app_id with 'The Codemagic app ID', which is adequate. The description does not add further semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'List' and the resource 'webhook subscriptions', and scopes it to 'configured for a Codemagic app'. This distinguishes it from sibling tools like delete_webhook or get_webhook_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 context about prerequisites, limitations, or when to prefer another tool is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the non-obvious behavior of yaml workflows appearing only after first build, but lacks details on authentication, pagination, error handling, or side effects. Adequate but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences (28 words) with no fluff. It front-loads the core action, then provides return info, a cross-reference, and a limitation. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one parameter and no output schema, the description covers the essential aspects: what it does, what it returns, how to use results, and a caveat. Minor gap: output structure not explicitly confirmed (e.g., array of objects), but still mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the description does not add significant semantics beyond the schema's parameter description. Baseline of 3 is appropriate as the description provides no additional format or usage details for app_id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 'workflows for an application', and specifies what is returned (names and IDs). It distinguishes itself from sibling list tools by focusing on workflows and mentions a specific use case with trigger_build.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells the agent to use the returned ID in trigger_build and notes a limitation (yaml-defined workflows appear only after first build). While it does not explicitly say when not to use it or compare with siblings, the context is clear and helpful.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits (e.g., auth requirements, whether it's read-only), but it only states the action. It does not confirm safety or non-destructiveness, leaving agents guessing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. It is front-loaded and efficient for its purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, parameterless listing tool, the description is minimally adequate. However, given sibling tools that use template types, it could be improved by explaining that the output feeds into tools like 'get_yaml_template'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the schema is complete (100% coverage). The description adds the context of 'all available' and 'codemagic.yaml template types', providing meaning beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

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 ('codemagic.yaml template types'), making it distinct from sibling tools like 'get_yaml_template' or 'validate_codemagic_yaml'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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., 'get_yaml_template' for a specific template). The description lacks context for an agent to decide between listing types and retrieving a specific template.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully discloses the tool's behavior: checking server liveness and returning its version. It is clear and transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that efficiently conveys the tool's purpose without any extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple ping tool, the description is complete enough. It indicates it returns a version, but lacks details on error handling or response format. However, given the simplicity, it is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters and the schema description coverage is 100%, so no additional parameter information is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'check' and the resource 'server', and it distinguishes from sibling tools that deal with builds, apps, and other specific operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives, but its purpose as a simple health check is evident from the context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses the tool's behavior: it checks BCP-47 locale codes and character limits per platform, with 'both' using Android's stricter limit. It does not mention side effects or response format, but as a validation tool, the core behavior is well described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with zero fluff. Front-loaded purpose, followed by necessary details. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter validation tool with no output schema, the description covers the validation rules and constraints adequately. It could mention return values (e.g., validation result structure) but is not strictly necessary given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes both parameters. The description adds value by explaining the 'both' platform option and the specific character limits (Android 500, iOS 4000), going beyond the schema's generic descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'validate' and clearly identifies the resource 'localized release notes' and the context 'before submitting to the App Store or Google Play'. It distinguishes from sibling tools like 'set_ios_store_listing' or 'upload_to_google_play' by focusing on validation, not submission.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states when to use the tool ('before submitting to the App Store or Google Play'), implying the workflow phase. It also provides guidance on using platform='both' for stricter validation. No explicit alternatives or when-not-to-use, but the context 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (readOnlyHint=false, destructiveHint=false). Description adds significant behavioral context: explains promotion without re-uploading, effects of user_fraction, halting, and resuming. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: first states purpose, second explains user_fraction, third covers halt/resume. Front-loaded, no redundant words, efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all parameters (package_name implied by standard schema), explains promotion workflow, staged rollout, and edge cases (halt/resume). No output schema needed; context fully supports correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, description adds meaning beyond enum values: explains user_fraction as staged rollout percentage (0.1 = 10%), and how release_status and tracks interact for halt/resume. This is highly informative.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool promotes releases between Google Play tracks without re-uploading, using specific verbs and resource. It distinguishes from siblings like upload_to_google_play (which involves uploading) and set_rollout_fraction (focused on rollout fraction, not track promotion).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit when-to-use: for staged rollout set user_fraction, for halting set tracks to production and release_status='halted', for resuming set same tracks with inProgress and user_fraction. Gives clear alternative scenarios and parameter combinations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that the tool immediately makes the update available or starts a phased rollout, adding behavioral context beyond the annotations. Annotations already indicate destructiveness, and the description elaborates the effect, though it could mention reversibility or prerequisites.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core action, and no wasted words. It efficiently conveys purpose, usage, and alternatives.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 required params, no output schema, annotations present), the description is complete. It covers purpose, state prerequisites, effects, and sibling alternatives adequately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, the description adds no additional meaning beyond the schema's parameter descriptions. It meets the baseline for high coverage but does not enhance parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool releases an approved App Store version from 'Pending Developer Release', specifying the verb and resource. It distinguishes itself from the sibling 'set_phased_release' by mentioning an alternative for gradual rollouts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use this tool (for versions in 'Pending Developer Release' state) and when not to use it (for gradual rollout, use set_phased_release instead), providing clear context and an alternative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that replies are limited to 350 characters and that existing replies are replaced. Annotations indicate not read-only and not destructive, which aligns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the action, concise and includes practical tips without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers all necessary aspects: purpose, parameter sources, constraints, and best practices. No output schema needed for this simple mutation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All parameters already have schema descriptions (100% coverage). The description adds value by indicating the source of review_id and reinforcing the character limit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Post or update a developer reply to a Google Play user review', specifying the verb and resource. Distinguishes from sibling tools like list_google_play_reviews and other mutation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Advises to get review_id from list_google_play_reviews and provides guidance on writing helpful replies. Could be more explicit about when not to use, but context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only indicate non-readOnly and non-destructive. The description adds critical behavioral context: 'Takes effect immediately — there is no staging step and no GET endpoint to retrieve current labels.' This reveals the immediate and irreversible nature 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a compact paragraph of five sentences, each adding essential information. It front-loads the main action and efficiently covers input source, usage scenarios, and behavioral implications without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has two well-described parameters, no output schema, and sibling tools, the description covers the key aspects: purpose, input format, when to use, and side effects. It does not explain the response or error handling, but the immediate effect note compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 adds value by explaining the source of the CSV ('exported from Play Console → App content → Data safety → Export CSV'), which supplements the schema's technical details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Submit' and the resource 'data safety declaration for a Google Play app', with additional context on what the declaration describes. It distinguishes from sibling tools that handle store listings, uploads, or other Google Play operations, though no explicit comparison is made.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description specifies when to use the tool: 'Re-upload whenever data practices change' and accepts CSV from a specific Play Console export path. It implies when not to use it (if no GET endpoint exists, avoid retrieval), but does not explicitly mention alternatives or exclusion scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate a write operation (readOnlyHint=false, destructiveHint=false). The description adds valuable behavioral details: partial update, immediate effect, and no staging. This provides deeper insight beyond the annotation schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first states purpose and key constraint, second adds behavioral note. No redundant or vague wording. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description sufficiently covers update behavior, partial update, and immediate effect. It could optionally mention return value, but for a mutation tool this is adequate. Completeness is high for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all parameters with descriptions (100% coverage). The description adds meaning by explaining the partial update semantics, which tells the agent that omitted fields are untouched. This is extra context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Update the Google Play store listing for a specific language,' which is a specific verb and resource. This differentiates it from siblings like get_android_store_listing (read) and upload_to_google_play (binary upload).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly notes partial update behavior ('Only the fields you provide are updated') and immediate effect ('Changes go live immediately on commit; there is no staging step'). While it doesn't explicitly compare to alternatives, the context signals show a distinct sibling set.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that it modifies export compliance status, which aligns with destructiveHint=false and readOnlyHint=false. However, does not discuss reversibility or side effects on existing submissions, but the mutation is straightforward.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three well-structured sentences with no fluff. First sentence states purpose, second gives context, third provides practical guidance. Front-loaded effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Provides sufficient context for a simple boolean setter with three parameters, including workflow relevance and parameter defaults. Could mention what happens after setting but not critical given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaningful context beyond the schema: explains why uses_non_exempt_encryption is needed and when to set true/false, and clarifies default for build_id. Schema coverage is 100%, so description supplements well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool sets export compliance declaration for iOS builds, with specific verb 'Set' and resource. Distinguishes from siblings by focusing on a compliance step not covered by other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when it's required (before App Store submission and TestFlight external distribution) and provides guidance on setting false for most apps vs true for custom encryption. Also explains default behavior for build_id parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations confirm non-read-only and non-destructive. Description adds partial update behavior, version scoping, and staging/validation process. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, no wasted words. Each sentence contributes useful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 12 parameters and no output schema, description covers behavior, scoping, and staging well. Slight lack of error handling details, but sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. Description groups fields into app-info and version categories, and clarifies partial update behavior, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Update App Store listing text for a single locale', specifying a precise verb and resource. The tool is distinct from siblings like get_ios_store_listing and set_android_store_listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: only provided fields change, omitted fields left as-is. Distinguishes app-info vs version field scopes. No explicit alternatives, but the scope is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With minimal annotations (only readOnlyHint and destructiveHint), the description adds extensive behavioral detail: the rollout timeline, stateful nature, and effect of each action. It explains prerequisites and recovery scenarios, fully carrying the transparency burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph, efficiently front-loaded with the tool's purpose. It sequentially covers the rollout concept, timeline, then each action with one-liner explanations. No redundant words; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

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 covers actions, timeline, and prerequisites well. Minor gaps: it doesn't specify if you can resume after complete, or describe return values. Overall, it's sufficiently complete for an AI agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by embedding actions in practical context (e.g., 'use if a critical bug is found' for pause). While schema already describes each enum, the description enriches meaning for an AI agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool manages a phased rollout for an App Store version. It explains the timeline and four actions. While it doesn't explicitly differentiate from sibling tools like set_rollout_fraction, the purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context for each action: create before submission, pause for critical bugs, resume to continue, complete to release fully. It gives practical scenarios, but lacks explicit exclusions or mention of alternatives (e.g., for immediate full release).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate the tool is neither read-only nor destructive. The description adds the precondition that the version code must correspond to a release currently in staged rollout. No additional behavioral traits (e.g., permissions, reversibility) 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description consists of two concise sentences. The first sentence states the purpose, the second provides usage guidance and a prerequisite. No unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and clear input parameters, the description covers the key aspects: purpose, usage scenario, required inputs, and a source for one parameter. It is mostly complete, though it could mention the outcome of the adjustment.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

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 provides a hint about where to get the version_code ('from list_google_play_tracks') but otherwise repeats schema information. Minimal added value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'adjust' and the resource 'staged rollout percentage for an existing release on a Google Play track'. It is specific and distinguishes from sibling tools like promote_google_play_release.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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 the tool ('to gradually expand a rollout') and a prerequisite ('requires the version code'). It does not explicitly mention when not to use or list alternatives, but the context is sufficient for most cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate this is a write operation (readOnlyHint=false). The description adds that What's New is required per Apple and that the call should be made once per locale. It does not contradict annotations and provides useful behavioral context, though it could mention permission requirements 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with the main purpose. Every sentence adds value (purpose, usage pattern, follow-up). No redundant or vague language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters (all well-documented in schema) and no output schema, the description provides sufficient context: identifies required fields, locale handling, and post-call validation step. An agent can correctly invoke this tool with the provided information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds practical semantics: notes that What's New is required for submission, explains the locale default (en-US) and suggests adding other locales if supported. This goes beyond the schema's field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update App Store version localization metadata') and specifies the exact fields (What's New, description, keywords, etc.). It distinguishes the tool from siblings like set_ios_store_listing (which handles store-level listing) and validate_app_submission (which checks submission readiness).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: before submitting for review, per locale, with en-US as required default. Also provides a clear follow-up step: 'Use validate_app_submission afterward.' No ambiguity about alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are non‑destructive and not read‑only. The description adds behavioral context: 'no track, no review, no version code ceremony' and explains the output (install URL). 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front‑loaded with the main action, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single‑parameter tool with no output schema, the description explains the return value and prerequisite, providing sufficient context for correct use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear description for aab_url. The description does not add further parameter details beyond the schema, so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (upload), the resource (AAB from Codemagic), and the result (install URL for internal app sharing). It distinguishes from siblings like upload_to_google_play by emphasizing no track or review.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives context for use ('Ideal for quick QA before promoting to a track') and a prerequisite ('Testers need the internal app sharing feature enabled'). It does not explicitly list when not to use or name alternatives, but the purpose 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate not read-only and not destructive, which aligns with the 'submit' action. The description adds behavioral context: Apple reviews once, then all external groups can access. 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is four sentences, each adding value. No fluff, front-loaded with the core action, and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one param, no output schema). The description covers prerequisites (build ID from list_asc_builds), the review process, and distinction between internal/external groups. Missing details like potential errors or delays, but adequate for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter (build_id) described. The description mentions 'Get the build ID from list_asc_builds', which reinforces but doesn't add significant new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action 'Submit a build for TestFlight beta app review' and explains its purpose (required before external beta groups can install). It distinguishes from sibling tools like 'submit_for_app_store_review' by specifying the TestFlight context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use this tool (before external beta groups can install) and when not (internal groups do not require beta review). It also provides a source for the build ID, but doesn't explicitly mention alternatives like 'share_app_internally'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate non-read-only and non-destructive. The description adds critical behavioral context: the build must have processingState VALID, and prerequisites must be met. It warns about expected states 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise, with two sentences. The first sentence states the core action, and the second provides essential usage guidance and an alternative. Every sentence is valuable and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter tool with no output schema, the description is complete. It includes prerequisites, alternative tools, and validation steps, ensuring the agent can use it correctly in context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add significant meaning beyond the schema parameter descriptions. It references build_id and version but provides no additional parameter-specific semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb and resource: 'Attach a processed build to an App Store version and submit it for review.' It distinguishes from siblings by referencing prerequisite tools like list_asc_builds and validate_app_submission.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidelines are provided: use only after the build's processingState is VALID (confirmed via list_asc_builds), and after setting version metadata and export compliance. The alternative validate_app_submission is mentioned for catching blockers.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are minimal (non-readonly, non-destructive). Description adds workflow context (validate yaml, wait for build) but does not disclose error cases, rate limits, or permission requirements. It explains yaml passing mechanism but lacks transparency on build costs or time.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Single paragraph front-loaded with main purpose, then details. Every sentence adds value, but could be structured with bullet points for readability. No wasted words, but slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (9 params, no output schema), description covers core usage flow and companion tools. Lacks return value format and error handling. Since no output schema, should describe response structure minimally.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions. Description adds extra meaning: explains how to use variables for BUILD_NUMBER in release builds, and specifies instance_type restrictions for personal accounts. Compensates for schema's lack of enums or detailed formats.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Trigger a new build on Codemagic' with specific verb and resource. It distinguishes from siblings by referencing companion tools like wait_for_build, get_yaml_template, and validate_codemagic_yaml.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidelines: for release builds, determine BUILD_NUMBER first; use yaml_content with validation; call wait_for_build after. Mentions alternatives indirectly but does not explicitly state when not to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate mutation (readOnlyHint=false) and non-destructiveness. The description adds critical behavioral context: it only applies to non-secret variables and warns against handling secrets via the agent, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero wasted words, front-loaded with the core action. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description covers the essential behavior and constraints. It lacks detail on error conditions or idempotency, but for a simple update tool, it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with good descriptions. The description adds value by explaining the origin of variable_id (from list_variable_groups), which helps the agent understand the parameter's relationship.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Update') and resource ('existing non-secret variable'), clearly distinguishing it from sibling tools like add_variable (create) and delete_variable (delete). The scope is well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states the source of variable_id and advises against using for secret values, guiding the agent away from misuse. However, it does not explicitly list when not to use (e.g., for public or read scenarios), 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses atomicity of uploads, supported formats (JPEG, 24-bit PNG), max file size (8 MB), and that replace=true deletes existing screenshots. Annotations confirm readOnly=false and destructiveHint=false, with 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.

Is the description appropriately sized, front-loaded, and free of redundancy?

Five sentences, front-loaded with the main action, then constraints and recommended usage. Every sentence adds necessary detail without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, constraints (format, size, limit), atomicity, and replace behavior. No output schema needed as tool likely returns status; description is sufficient 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.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds value by noting screenshot_urls are in display order, replace=true deletes all existing, and lists common image_type values beyond the schema's enum-like list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool downloads screenshots from URLs and uploads them to Google Play for a specific language and device type. This clearly distinguishes it from siblings like upload_ios_screenshots.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides specific guidance on the 8-screenshot limit, replace=true recommendation, and listing common image types. Does not explicitly state when not to use but offers clear context for typical scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.