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

Annotations declare readOnlyHint=true and the description's 'Report' language is consistent. The description adds useful behavioral context: it explains what the report covers (token validity, write enabling, remediation instructions) and the diagnostic role of this tool. 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?

Two sentences, both information-dense and purposeful. The first sentence states the tool's core output; the second gives actionable usage guidance. No filler or repetition.

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 diagnostic tool with readOnly annotation and no output schema, the description fully covers what the agent needs: what is reported, why to call it first, and how to interpret the absence of tools. Nothing important is missing.

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 there is nothing for the description to add beyond the schema. Per the baseline for 0-parameter tools, a 4 is appropriate since no parameter ambiguity exists.

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 ('Report') and a precise resource ('CloudKit management token', 'whether writes are enabled'). It clearly distinguishes itself from sibling tools that list containers, record types, or export schemas by focusing on authentication and configuration status.

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 when-to-use guidance: 'Call this first when a tool you expected is not listed'. It also interprets the meaning of an absent tool as missing configuration rather than a bug, which directly helps an agent decide to call this tool before diagnosing further.

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, and the description reinforces this by saying it only shows what would change. It adds important behavioral context beyond the annotation: production is additive-only and irreversible, fields can be added but never removed/renamed/retyped, and a non-additive diff is a stop signal. This is valuable interpretive guidance for the 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?

Three sentences, each earning its place: first states the core purpose, second gives workflow placement, third warns about production irreversibility. The most important scoping information is front-loaded, and there is no redundant 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 read-only diff tool with one optional parameter and no output schema, the description adequately explains the return shape ('one row per change') and the critical production constraints needed to interpret results. It could detail the exact fields present in each diff row, but the description provides enough context for correct invocation and basic interpretation.

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 does not elaborate on the containerId parameter, but schema description coverage is 100% and the parameter already has a clear description with an example and fallback via CLOUDKIT_CONTAINER_ID. The baseline 3 applies because the schema carries the semantic weight and the description adds no extra parameter meaning.

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 opens with a specific verb and resource: 'Show what deploying would change: the pending differences between the container's DEVELOPMENT and PRODUCTION schemas, one row per change.' This states exactly what the tool does and its output granularity. It also distinguishes itself from schema validation and export siblings by framing the output as a deploy-impact diff.

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 explicit sequencing guidance: 'Read this before cloudkit_deploy_schema.' This tells the agent when in a workflow the tool is valuable. It does not explicitly name alternatives or when not to use it, but the pre-deploy context is a clear usage signal.

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 readOnlyHint=true already declared, the description adds useful behavioral detail: the tool can return the schema text or write it to outputPath and report the destination. This meaningfully explains the two execution modes without contradicting the annotation.

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

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

The description is concise, front-loaded with the core purpose, and every sentence earns its place by adding behavioral or routing information. There is no redundant 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 simple read-only export tool with fully documented parameters, the description covers the output behavior, the optional file-writing path, and the relevant sibling alternative. Nothing critical is missing for an agent to call it 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 the input schema already documents all parameters effectively. The description adds little parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb and resource: exporting an environment's full schema as a `.ckdb` document. It also differentiates the tool from cloudkit_diff_schema, making its role among siblings immediately clear.

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 meaningful usage context by explaining that exporting both environments and diffing locally is one way to review a pending change, then names cloudkit_diff_schema as the more direct alternative. It stops short of giving explicit when-to-use/when-not-to-use rules, but 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 readOnlyHint annotation already establishes safety, and the description adds meaningful scope by noting it lists only containers 'this team can manage' and that the ids are the tool's key output. It does not discuss return format or errors, but the tool is simple enough that this is acceptable.

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

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

The description is two succinct sentences with no filler. The primary action and result are front-loaded, and the stated purpose directly supports agent 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?

For a zero-parameter, read-only listing tool, the description fully conveys what it does, what it returns, and why an agent would call it. Nothing essential is missing.

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 zero parameters and 100% schema description coverage, there is no parameter burden for the description to carry. The baseline of 4 applies, and the description adds no unnecessary parameter 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 'List' and the resource 'CloudKit containers this team can manage', and identifies the output as ids. It is immediately distinguishable from sibling tools by describing its specific 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 explicitly says to use this tool to find the container id that 'the other cloudkit_* tools take'. This directly tells an agent when this tool is needed and how it relates to all sibling 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?

Beyond the readOnlyHint annotation, the description adds meaningful behavioral context: Core Data and SwiftData prefix record types and fields with CD_, so names appear transformed. It also discloses that a field missing from DEVELOPMENT has not been written by any client yet, which is useful deployment-relevant 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 three sentences with the main action front-loaded. Every sentence earns its place: purpose, naming convention, and an important interpretation of absence. There is no filler 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 read-only listing tool, the description covers the key context: what is listed, how names are transformed, and what field absence means in DEVELOPMENT. It does not describe the output shape, but given the tool's simplicity and lack of output schema, this 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%, so the baseline is 3. The prose does not add much parameter-specific meaning beyond reinforcing environment separation, but the schema already documents environment, containerId, and recordType clearly.

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 opens with a specific verb and resource: 'List a container environment's record types and their fields.' It clearly states what the tool does and even frames it as how to confirm a newly added field reached CloudKit. However, it does not explicitly differentiate this tool from siblings like cloudkit_export_schema or cloudkit_diff_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?

The description gives a concrete use case: 'This is how you confirm a newly added field actually reached CloudKit.' It also explains the meaning of a missing DEVELOPMENT field, which helps the agent decide when this tool is useful. It does not mention when not to use it or name alternative 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?

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Only GET is available while writes are disabled,' adding the mechanism and current disabled-writes context. It also discloses that the API is undocumented, which sets expectations for raw/unpredictable responses. It does not detail error or response shapes, but the read-only annotation lowers that burden.

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

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

The purpose is front-loaded and the usage rule is compact. The second sentence is slightly wordy in explaining why the escape hatch exists, but it earns its place by justifying the tool's existence among specific siblings. No meaningful 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 an arbitrary raw-request tool, the description and schema together give what an agent needs to invoke it: an absolute path, GET-only availability, and the preference for specific tools. No fixed output schema is expected for raw requests, so omitting return details is acceptable. The only minor gap is lack of explicit guidance about response/error formats.

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 the schema already documents path, body, method, and confirm. The description adds the important constraint that only GET is currently available, which clarifies method semantics, but it does not provide additional parameter-level guidance beyond what the schema already contains.

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 opens with 'Escape hatch: issue an arbitrary CloudKit management API request,' which states a specific verb and resource. It also distinguishes itself from siblings by explicitly saying the other cloudkit_* tools cover the documented routes and that this exists for undocumented or differently-shaped endpoints.

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 gives a clear preference rule: 'Prefer a specific tool when one fits,' which tells an agent when NOT to use this tool. It also states the current constraint: 'Only GET is available while writes are disabled,' so the agent knows the only supported method before invoking.

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, and the description reinforces that with 'Read-only' and 'changes nothing.' It additionally clarifies that no import is performed, which is useful behavioral context beyond the structured annotation.

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 wasted words. The action and resource are front-loaded, and each clause adds meaningful information about scope and side effects.

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 read-only validation tool, the schema plus description cover required parameters and the high-level return meaning. The description could be slightly more explicit about output shape or authentication prerequisites, but nothing essential is missing for invoking the tool 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?

The input schema already describes filePath, containerId, and environment with full coverage. The description adds no new parameter-level detail beyond restating the file and environment concepts, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('validate'), names the exact resource (local .ckdb file), and states the outcome: reports whether the schema would be accepted. It also contrasts with importing, which helps distinguish it from mutation-style operations even without naming 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 phrase 'without importing it' implies this is a pre-import compatibility check, so some usage context is present. However, it does not explicitly say when to choose this over siblings like cloudkit_diff_schema or cloudkit_export_schema, nor does it provide exclusions or alternative routing.

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