codemagic

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description adds nothing beyond that: it doesn't say whether the cancellation is reversible, what build state results, whether artifacts are affected, or what error occurs for a non-running build. The REST endpoint line is metadata, not 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 sentences, action front-loaded, zero filler. Everything present earns its place, even if more could reasonably be said.

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 one-parameter mutation tool with destructiveHint annotations and no output schema, the definition is minimally viable: an agent knows what it does and that it is destructive. It is missing the post-condition and edge-case behavior that a cancel operation arguably warrants.

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% for the single buildId parameter, whose description already states 'The build id to cancel.' The description's 'by id' restates the schema rather than adding format or sourcing guidance, so the baseline 3 for full schema coverage 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?

States a specific verb and resource ('Cancel a running build by id') and names the scope ('running'), which cleanly separates it from siblings like codemagic_get_build, codemagic_list_builds, and codemagic_start_build without needing to name 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 phrase 'running build' implies a precondition, but there is no explicit when-to-use guidance, no statement about what happens if the build is already finished or invalid, and no reference to alternatives. Usage is left to inference.

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

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

Annotations only supply destructiveHint=true; the description usefully discloses the trait that explains it — the resulting URL is public, shareable and time-limited, meaning the artifact is exposed beyond the authenticated account. It does not mention auth requirements, rate limits, or whether previously issued URLs are revoked, so it stops short of full transparency.

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

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

Two tight sentences, front-loaded with the action and scope, followed by the REST endpoint mapping. Every clause earns its place; no filler.

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 mutation tool there is no output schema, so the description arguably should say what comes back (the URL and its expiry), and it omits the sibling-alternative routing that matters most here. Adequate but with clear 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 description coverage is 100% — both secureFilename and expiresAt (UNIX seconds) are fully documented in the schema. The description restates 'by its secure filename' and the time-limited nature but adds no syntax, format, or constraint information beyond what the schema already provides.

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

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

States a specific verb (Create) and resource (public download URL for a build artifact), and the qualifier 'public (shareable, time-limited)' implicitly contrasts with the authenticated sibling codemagic_get_artifact_download_url. An agent can tell what it produces without opening the schema.

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

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

Usage is implied by 'public (shareable, time-limited)' — you use this when you need an external, expiring link — but the description never names the obvious alternative codemagic_get_artifact_download_url or states when-not to use this one. No explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the REST mapping (GET /apps/{id}), which is modest extra context but says nothing about errors for unknown ids, auth requirements, or response content.

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, front-loaded sentences with no filler; the REST mapping sentence earns its place for agents that map tools to endpoints, though it is arguably redundant.

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?

A simple single-parameter read tool with annotations covering safety and the parameter fully documented; only the absence of any hint about return content or id-mismatch behavior keeps it short of 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 description coverage is 100% with a single, fully documented 'id' parameter, so the baseline is 3. The description's 'by id' adds no meaning beyond what the schema already states.

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?

States a specific verb (get) and resource (a single application), and clarifies the singular scope versus the sibling codemagic_list_applications. It does not name the sibling explicitly, but 'a single application by id' is enough for an agent to distinguish it.

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?

There is no when-to-use guidance, no prerequisites, and no mention of the obvious alternative (codemagic_list_applications) for discovering apps. Usage is only implied by the verb and the required 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?

The readOnlyHint annotation already declares this is a safe read. The description adds genuinely useful context beyond that, namely that the returned URL is authenticated and requires the secure filename rather than a plain artifact name. It omits expiry/lifetime of the URL and any permission requirements, which would be the natural next detail for a download-URL 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 compact sentences, front-loaded with the purpose, with the parenthetical provenance of the parameter and the REST endpoint appended only after the core statement. No filler.

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 one-parameter, read-only lookup with no output schema, the description covers what the tool returns (an authenticated download URL) and where the input comes from. Only the URL's lifetime/validity is unaddressed, which is a minor gap.

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% for the single parameter, so the schema already documents secureFilename. The description restates that it comes from a build's artifacts list and shows it in the REST path, adding only marginal meaning. 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?

States a specific verb+resource+scope: get an authenticated download URL for a build artifact identified by secureFilename, plus the backing REST endpoint. It does not name or contrast with the sibling codemagic_create_artifact_public_url, which is the natural confusion case, so it stops short of a 5.

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

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

Usage is implied: the caller must already have a secureFilename sourced from a build's artifacts list. There is no explicit when-to-use versus when-not, and no routing to the public-URL alternative when an unauthenticated link is wanted.

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 readOnlyHint annotation already establishes this as a safe read. The description adds that the response includes build status and pins the underlying REST call (GET /builds/{id}), which is mild but real context; it does not cover error behavior for an unknown id or any 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 short sentences, zero filler, with the core action front-loaded and the endpoint mapping placed last as supporting detail.

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 read tool with no output schema, the description is nearly sufficient, naming the key returned field (status). Only error/not-found behavior and the full return shape remain unstated, which is minor.

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 single buildId parameter is fully documented in the schema, so the baseline is 3. 'By id' in the description adds no syntax or format detail 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?

States a specific verb and resource ('Get a single build by id') and names the detail returned ('including its status'), and the word 'single' implicitly contrasts with the sibling codemagic_list_builds. It stops short of explicitly naming alternatives, so it is clear but not fully differentiated.

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?

There is no statement of when to use this tool versus codemagic_list_builds or codemagic_get_application, and no mention of prerequisites such as a valid/known build id. Usage is only inferable from the phrase 'by id'.

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 the safety profile is covered. The description adds the backing REST endpoint (GET /apps) and the shape of what is returned, which is useful context, but nothing about pagination, scope limits, or ordering.

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

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

A single tight sentence with the resource and returned fields front-loaded. The trailing 'Codemagic REST: GET /apps' is mildly redundant but arguably useful orientation for an API-aware agent.

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 zero-parameter read tool with no output schema, the description covers the returned fields and the source endpoint, which is enough for an agent to call it correctly. Only pagination/ordering behavior is unaddressed.

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 takes zero parameters, so per the rubric the baseline is 4. The description correctly adds no parameter detail because there is none to add.

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?

Clear verb+resource: 'List all applications (apps) in the Codemagic account' and enumerates the returned fields (ids, names, workflow ids). It contrasts implicitly with the singular codemagic_get_application via 'all', but never names the sibling, so the differentiation is only inferable.

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 when-to-use or when-not-to-use guidance. The presence of codemagic_get_application in the sibling list makes a list-vs-fetch rule worth stating, and it is absent. Usage is only implied by the verb.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description need not restate safety. It adds the underlying REST mapping (GET /builds), which is mildly useful for developers, but says nothing about pagination, result limits, or ordering — gaps that matter for a list endpoint.

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, filter scope front-loaded and the REST mapping tucked at the end. Every clause carries information; nothing is padding.

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 zero-required-parameter list tool with no output schema and read-only annotations, the description covers purpose and filterability adequately. The only meaningful omission is pagination/result-size behavior, which is a minor gap rather than a blocking one.

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 all three filters are already documented in the schema. The description only enumerates the same filter dimensions (application, workflow, branch) without adding format, matching behavior, or combination semantics, so baseline 3 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?

States a specific verb (List) and resource (builds) with scope of optional filters, which cleanly separates it from codemagic_get_build (single build) and codemagic_list_applications. It does not explicitly name a sibling, so it stops short of a 5.

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

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

The phrase 'optionally filtered by' implies the tool is for browsing/enumerating builds and that filters are optional, but it gives no explicit when-to-use versus codemagic_get_build or when-not to use it. Usage is inferable but not stated.

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 the safety profile is covered. The description adds the underlying REST call (GET /apps/{appId}/caches) and the shape of returned fields, but says nothing about pagination, cache retention, or permissions.

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

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

Two tight sentences; the purpose and returned fields are front-loaded and the REST endpoint follows as supporting detail. 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 read-only list tool with annotations covering safety and no output schema, the description supplies enough to invoke it correctly. Minor gaps around pagination and result limits keep it from being 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 there is only one parameter (appId), fully documented in the schema. The description adds no syntax or format meaning beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List the build caches for an application') and enumerates the returned fields (id, size, last used, workflow). No sibling tool covers caches, so no explicit differentiation is needed, though none is given.

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?

There is no when-to-use, when-not-to-use, or alternative-tool guidance. The usage context is only inferable from the tool name, which is the minimum for a simple read 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 declare destructiveHint=true, so the mutation profile is partly covered, but the description adds no behavioral context beyond that: it does not say builds consume build minutes/credits, are asynchronous, or require authentication. The only extra is the REST mapping 'POST /builds', which is marginal.

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 short sentences with requirements front-loaded ('appId and workflowId are required') before the optional surface. No redundancy or filler; every clause carries 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?

There is no output schema, yet a start-build tool's key output is the created build ID needed to poll codemagic_get_build or cancel it; the description never mentions what comes back or how to track the run. For a 7-parameter mutating tool with a nested object, that is a meaningful omission.

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 every parameter (including the nested environment object and instanceType examples) is already documented in the schema. The description merely restates required vs optional fields without adding format, allowed-value, or precedence detail, so the baseline 3 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?

States a specific verb and resource ('Start a new build for an application workflow'), which cleanly separates it from siblings like codemagic_cancel_build and codemagic_get_build. The remaining sibling (e.g., list_builds) is not explicitly named, but the action is 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?

Notes the two required parameters and that branch/tag are alternatives for targeting a revision, which is actionable context. However, it gives no guidance on when to prefer starting a build here versus querying existing builds, and no prerequisites (auth, app/workflow must exist) are stated.

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