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

Annotations already provide readOnlyHint=true, so the 'Read-only' statement is redundant. However, the description adds valuable non-annotation context: it reveals the return contents (target state of charge per plug type, AC and DC) and a provenance claim ('Verified live against a real vehicle'). This is meaningful for an agent because there is no output 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?

Three short sentences with no fluff. The core action and resource are front-loaded, the output detail is compact, and the read-only note and verification claim each add relevant context. 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 simple single-parameter read tool, the description is complete: the only parameter is fully documented in the schema, read-only behavior is declared in both annotations and description, and the output is described (charge targets per plug type) even though no output schema exists. An agent has everything needed 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%, and the vinKey property is well-documented ('Vehicle key... Not the VIN'). The description adds no parameter-level detail, but because the schema already fully covers the parameter semantics, 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 ('Read'), a specific resource ('EV charge targets (`evc/gts`)'), and the output shape ('target state of charge per plug type... AC, one for DC'). Clearly distinguishes from sibling write tools like kia_start_charge, kia_stop_charge, and kia_set_charge_limits by emphasizing read-only.

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: this is a read operation for charge targets and explicitly says it 'makes no changes'. This implicitly excludes using it to modify targets, and the read-only framing separates it from write siblings. It does not name an explicit alternative tool or state when-not-to-use it, so it stops short of a full 5.

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

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

Beyond the annotations, the description discloses the token's MFA-bypassing severity, vehicle-control implications, the prohibition on logging/displaying the value, and the two-phase confirmation behavior where the first call makes no network call. This is rich behavioral context that directly informs safe agent behavior and does not contradict the annotations.

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

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

Every sentence carries necessary security or usage information, and the most critical warning is front-loaded. Despite length, there is no filler; the structure flows from threat level to purpose to exclusions to confirmation protocol.

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 credential-sensitive nature, the two-step confirmation flow, and the absence of an output schema, the description is remarkably complete. It describes both phases of the fallback flow, the expected return pieces, and the constraints an agent must respect, leaving no critical gap for correct 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?

The schema already documents confirmToken with 100% coverage, and the description adds crucial operational semantics: it is only for the two-step fallback, must come from this same tool's phase-1 response, must never be invented or reused, and is ignored for clients supporting elicitation. This goes well 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 states a specific verb and resource: 'Return the stored Kia remember-me token (rmtoken) IN PLAINTEXT.' It also clearly differentiates this tool from kia_session_status by naming the session-checking sibling as the wrong tool for that use.

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 when to use this tool ('moving a locally-bootstrapped session into a hosted deployment') and when not to ('Do NOT call it to "check the session" (use kia_session_status)'). It also provides detailed confirmation-flow instructions, leaving no ambiguity about the correct calling pattern.

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 idempotentHint=true and destructiveHint=false, but the description goes beyond by stating it makes NO network call and includes a confirmation step, which is critical behavioral context. Some ambiguity about the confirmation flow (client-dependent) is acknowledged, but the description handles this well.

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 verbose but each sentence carries essential information about system behavior and confirmation. It could be tightened slightly, but given the complexity of the confirmation protocol and the need to prevent misuse, the length is justified.

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 has only one parameter, no output schema, and the description covers all necessary information: what the tool does, when to use it, the confirmation flow, and the absence of network calls. Nothing critical is missing for correct 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%, but the description adds crucial semantics for confirmToken: it explains when to use it (two-step fallback), when not to use it (never on first call, never invented), and the lifecycle (passed back after user approval). This goes beyond just 'only for confirmation' to cover the exact protocol.

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 specific resource (locally stored Kia session/remember-me token) and the action (discard). It also differentiates from siblings by stating the only alternative (manual file deletion) and the recovery context (token revoked, password changed).

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 describes when to use this tool (when stored token no longer works due to revocation, password change, or device change) and what it does NOT do (makes no network call, Kia is not told). It also mentions the alternative (manual file deletion) and the confirmation flow, providing clear usage context.

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

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

Annotations already provide readOnly, idempotent, and openWorld hints, but the description adds meaningful behavioral detail beyond those: it states that exactly one authenticated request is made, that the credential itself is never returned, and that the output classifies failure modes ('no credential' vs 'credential rejected' vs 'Kia Connect-side problem'). This gives agents a clear safety and side-effect profile not available from the annotations alone.

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

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

The description is ~100 words, front-loads the core action, then reports the output, then the read-only/security note, and ends with the usage trigger. Every sentence carries distinct information; 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?

With no output schema, the description compensates by detailing what the tool reports (credential source, acceptance, RTT, hint) and what it never returns. Combined with the input-free schema and annotations, an agent has all necessary information to invoke this tool correctly and interpret its result.

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 zero parameters and the schema coverage is 100%, so there are no parameter semantics to explain. The baseline of 4 applies, and the description accurately avoids inventing any parameter-related content.

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 ('Resolves the credential... makes one authenticated request to Kia Connect') and enumerates the exact outputs (credential source, acceptance, RTT, plain-English hint). It also positions itself against siblings via 'Call this when a real tool fails' and its read-only diagnostic nature, clearly distinguishing it from vehicle command, auth-flow, and session 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 gives a clear trigger condition: 'Call this when a real tool fails and you want to know which hop broke.' This is strong when-to-use guidance. It does not explicitly name alternatives or state when-not-to-use, but the diagnostic purpose is unambiguous in context with the sibling list.

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 readOnly, openWorld, and idempotent hints. The description adds useful context like VIN masking and the list of returned fields, which goes beyond the annotations.

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

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

Two concise sentences that front-load the purpose and key outputs, with 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?

Given zero parameters and no output schema, the description fully explains the tool's behavior, including what fields are returned and the VIN masking policy.

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, the baseline is 4. The description adequately explains that no input is needed, and schema coverage is 100%, so no further param info is required.

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 'List the vehicles enrolled on this Kia Owners account' with a specific verb and resource, and distinguishes itself from sibling tools by highlighting that it returns the vehicleKey needed 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?

The description implies that this tool is a prerequisite because it returns 'the id every other Kia tool takes,' but it does not explicitly state when to use versus 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?

Beyond annotations, it discloses that the call wakes the telematics unit, is slower, draws power, and that Kia only acknowledges the request without returning data or a completion signal. This paints a clear behavioral model beyond readOnly/idempotent hints and does not contradict them.

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 dense sentences front-load the purpose, then cover latency/power trade-off, usage preference, and asynchronous behavior. Every sentence earns its place with 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?

The described async/no-return behavior compensates for the missing output schema, and the follow-up instruction to read kia_vehicle_status completes the workflow. With one optional, well-documented parameter, nothing critical 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?

Schema coverage is 100% and the sole parameter is already fully documented with type, source, and default behavior. The description does not add parameter-specific meaning, but none 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 names the action ('Ask the car for a fresh reading'), the target resource (rems/rvs, requestType 0), and distinguishes it from kia_vehicle_status. It is immediately clear this is a refresh trigger versus the cached read.

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 contrasts with kia_vehicle_status, states when to prefer the cached read ('unless staleness matters'), and instructs to call kia_vehicle_status afterwards to observe results. This is unambiguous guidance on when and how to use the tool.

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

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

The description adds behavioral context beyond annotations: it notes the passcode expires in about two minutes and that expiresAt reports when, and that it lacks a separate confirmation gate. The annotation destructiveHint=true indicates potential side effects, but the description does not contradict this. However, it doesn't elaborate on the destructive nature (e.g., sending SMS may incur costs), so minor gap remains.

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 but rich: it conveys the step, dependencies, user interaction, expiration, and reporting in four sentences. It is front-loaded with the purpose and dependency, making it easy to scan. Every sentence adds value, and there is no fluff.

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 the key aspects: prerequisites (otpKey, xid), user interaction (ask channel), expiration, and result (expiresAt). With no output schema, it hints at the response containing expiresAt, which is useful. It could mention error handling or what happens if the OTP is not sent, but for a step in a multi-step flow, it's sufficiently 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 each parameter already described. The tool description reinforces the dependency on otpKey and xid from kia_start_login, adding slightly more context about their source. For notifyType, it reiterates the instruction to ask the user, aligning with the schema. Since the schema is thorough, the added value is modest but not redundant.

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 is 'Step 2 of the Kia MFA bootstrap (cmm/sendOTP)' and that it delivers a one-time passcode via SMS or email. It distinguishes itself from kia_start_login and kia_verify_otp by explicitly referencing the flow order, making its purpose unambiguous.

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

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

The description explicitly says it 'cannot run without' the otpKey and xid from kia_start_login, making the dependency clear. It also instructs the agent to ask the user which channel to use and not to guess, which is crucial for correct usage. It does not explicitly name alternatives, but given the MFA bootstrap context, it's evident 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?

Beyond annotations (readOnlyHint, idempotentHint), the description adds that the tool makes no network call, returns no secret, masks sensitive data (email, device id), and never includes session id or remember-me token. This fully discloses behavior 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 two sentences, front-loaded with purpose, then security details. Every word is valuable, no redundancy. Highly concise 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?

Given zero parameters and no output schema, the description fully covers the tool's purpose, behavior, security posture, and usage context. 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?

With zero parameters and 100% schema coverage, the description does not need to add parameter info. It focuses on the output behavior, which is appropriate. Baseline 4 for zero parameters.

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 checks server configuration and login status for Kia, including credentials, MFA bootstrap, and registered commands. It distinguishes itself by noting it makes no network call and returns no secret, setting it apart 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?

The description explicitly says 'Start here when a Kia tool reports it is not configured,' providing clear guidance on when to use this tool. It does not explicitly mention when not to use it, but 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?

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds crucial behavior: the write is verified by re-reading evc/gts, the first call in fallback mode makes no network call and returns a preview+confirmToken, and the preview step makes no call at all. This fully discloses the side effects and state changes, far exceeding annotation coverage.

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

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

The description is dense but every sentence earns its place: the core action, verification behavior, list-replacement warning, confirmation flow, and fallback detail. It is front-loaded with the purpose and proceeds logically. 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?

Given the tool's complexity (confirmation, verification, replacement semantics), the description covers all necessary context. It explains the two-phase behavior, the impact of omitting entries, and the verification step. With no output schema, it also describes what the preview response contains. 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?

Schema description coverage is 100%, so the baseline is 3. The tool description does not add new parameter-level meaning beyond what the schema already provides (e.g., plugType mapping, targetSOClevel range, confirmToken usage). The schema itself is detailed, so the description correctly relies on it without redundancy.

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 precise verb-resource pair: 'Set the target state of charge per plug type'. It clearly distinguishes this from the sibling kia_charge_targets (likely a read operation) and from start/stop charge tools. The purpose is unmistakable.

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 instructions: send BOTH plug types because the list replaces the stored one, read current targets first (echoed in schema), and handle the confirmation flow. It explains the two-step fallback and when the confirmToken is needed, leaving no ambiguity about how to invoke the tool correctly.

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 annotations, the description discloses several critical behaviors: the call is a no-op on an unplugged car, the first call may make no network request and instead return a preview with confirmToken, a second call with that token is required, and the battery charge state can take 30–60 seconds to update. It also warns not to trust the success status, which is valuable operational context. No contradiction with the annotations exists.

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

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

The description is dense but every sentence earns its place: purpose, expected behavior, prerequisite, verification instruction, and confirmation mechanics. It is front-loaded with the core action and each subsequent detail addresses a real operational risk or workflow requirement. There is no filler or redundant restatement of the tool name.

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

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

Despite having no output schema, the description supplies the essential response-level information: a preview plus confirmToken on the fallback path, the observable success signal (evStatus.batteryCharge), the timing, and the need to verify with kia_vehicle_status. For a mutating, user-confirmation-gated tool, this is sufficient for an agent to select and invoke it correctly.

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

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

The input schema already provides 100% parameter coverage with clear descriptions, so the baseline is 3. The description adds meaningful workflow semantics around confirmToken: it explains that the token comes from a phase-1 preview response, must be passed back only after explicit user approval, and only with the same arguments. This goes beyond the schema by connecting the parameters to the two-step confirmation behavior.

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 a specific action ('Ask the vehicle to start charging') tied to a concrete endpoint (`evc/charge`), and it is clearly distinguishable from sibling tools like kia_stop_charge and kia_vehicle_status. It leaves no doubt about what resource is being acted on and what the intended outcome is.

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 strong contextual guidance: the car must be plugged in, otherwise the request is accepted but does nothing; the tool should not be trusted for confirmation, with kia_vehicle_status named as the verification path; and user confirmation is required first. It does not explicitly compare against alternatives like kia_stop_charge, but the constraints and workflow are clear enough for an agent to decide when to use it.

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

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

Beyond the annotations, it discloses major behaviors: the first call may make no network call, a repeat call with confirmToken is required, the tool re-reads cmm/gvi until nested climate.airCtrl is true, EV ignition behaves differently, and temperature is best-effort. It also documents that seat and accessory heating are deliberately omitted from the request.

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 long but every clause earns its place, covering confirmation, verification, EV quirks, timing, temperature fidelity, and omitted features. The core action is front-loaded and the supporting caveats are ordered logically without 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?

Given the tool's complexity, the lack of an output schema, and the need to safely handle confirmation and idempotency, this description is unusually complete. It explains response phases, acceptance-vs-confirmation semantics, timing expectations, and what the tool does not do, so an agent has enough context to invoke 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 coverage is 100% and the schema fields are already richly described. The description adds extra semantic nuance on top: temperature is unconfirmed, waitSeconds above ~45 can outlast client timeouts, and confirmToken must only be reused after explicit user approval. This goes beyond the baseline, though not every parameter receives extra description-level detail.

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 opening sentence states a specific verb and resource: "Start remote climate control / preconditioning (Kia `rems/start`, live-verified)." This clearly distinguishes it from siblings like kia_stop_climate and kia_start_charge by domain, action, and endpoint.

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 strong operational guidance: when to expect a preview and confirmToken, when to re-read instead of re-sending, and how to handle unconfirmed results. However, it never explicitly names when to choose this over sibling tools, relying on the purpose statement to imply the use case.

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 annotations, the description reveals a two-phase confirmation flow, no network call on first invocation in fallback mode, and a severe failure mode: failed logins can trigger reCAPTCHA that permanently breaks server-side login. It explains that rejections are never retried, which is exactly the kind of context annotations alone cannot 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 dense but every sentence carries necessary risk or flow information. It front-loads the purpose and usage condition before explaining the confirmation fallback and consequences, and uses the warning at the end to justify caution without 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 one-parameter tool with no output schema, the description covers the trigger condition, expected return values (otpKey, xid, preview, confirmToken), the repeat-call protocol, and the high-consequence failure behavior. There is no critical gap an agent would need in order to call this 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 schema already describes confirmToken in detail, so the baseline is 3. The description adds meaning by tying the token to the two-step confirmation mode, noting it is ignored when the client supports elicitation, and reinforcing that a repeat call must use the same arguments. This clarifies when and how the parameter should be used.

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: Step 1 of the Kia MFA bootstrap, sends configured credentials, and returns otpKey plus xid for the next two steps. This clearly distinguishes it from sibling session/token tools like kia_session_status and kia_send_otp.

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 states explicitly that the tool is only needed when kia_session_status reports hasSession:false and that the bootstrap happens once, after which the stored remember-me token refreshes sessions silently. The confirmation requirement is also described, eliminating ambiguity about when a second call may occur.

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 annotations indicating readOnlyHint=false and destructiveHint=false (it's a state-changing but non-destructive operation), the description goes beyond annotations by disclosing the confirmation behavior: it may return a preview and confirmToken without making a network call, and that a repeat call is needed. It also warns about not trusting success status and suggests verifying with a sibling tool. This fully discloses the tool's side effects and asynchronous nature.

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 but packed with essential information: primary action, verification advice, and confirmation flow. It is front-loaded with the core purpose, then provides critical usage details. Every sentence earns its place; no fluff or redundant phrasing.

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 2 parameters, the description is comprehensive. It covers the action, the confirmation caveat, the verification step, and the exact scenario for using confirmToken. Given the tool's moderate complexity (state-changing, confirmation-dependent), the description leaves no critical gaps 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?

The input schema already provides descriptions for both parameters, including the pattern and that vinKey is not the VIN. The description adds important context for `confirmToken`: it clarifies that it is only for non-elicitation clients, must not be invented or reused, and is ignored with elicitation. This adds meaning beyond the schema, justifying a score above baseline 3 (schema coverage is 100%).

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 primary function (ask vehicle to stop charging) and specifies the underlying command (`evc/cancel`), distinguishing it from siblings like `kia_start_charge` and `kia_set_charge_limits`. The verb 'stop' and resource 'charging' are precise, and the verification hint adds 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 provides explicit guidance on when to use this tool (to stop charging), and explicitly recommends confirming via `kia_vehicle_status` instead of trusting success status, which differentiates it from siblings. It also details the two-step confirmation protocol, clarifying when the first call makes no network call and when a repeat call with confirmToken is needed, guiding the agent on the correct invocation sequence.

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 annotations already present, the description still adds substantial behavioral context: the no-network-call first phase, re-reading cmm/gvi until the NESTED `climate.airCtrl` reads false (warning there is no flat `airCtrlOn` field), the separate `commandAccepted` vs `stateConfirmed` semantics, and observed 30–60s state-change latency. The idempotentHint=true annotation aligns with the advice to re-read status rather than re-send, and no contradiction exists.

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

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

A single dense paragraph around 120 words with no filler; purpose is front-loaded, and the flow (confirm → verify → result semantics → timing) reads naturally. Given the genuinely complex behavior being encoded — two confirmation modes, polling, nested fields — the length is earned, though headers could marginally improve scannability.

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 complex action tool with no output schema, the description compensates by naming the key result concepts agents must interpret: preview, confirmToken, commandAccepted, stateConfirmed, and ign3, plus the nested-field gotcha and timing expectations. It doesn't enumerate every possible failure mode (e.g., expired Kia session), but the essentials for correct invocation and result interpretation are covered.

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% — vinKey, waitSeconds, and confirmToken each have thorough schema descriptions including the timeout behavior and the token lifecycle. The main description adds no parameter-level meaning beyond what the schema already provides, so the high-coverage 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?

The description states a specific verb and resource — "Stop remote climate control (Kia `rems/stop`, live-verified)" — naming the underlying endpoint and the verification behavior. This unequivocally distinguishes it from siblings like kia_start_climate and the charge tools even before considering the confirmation-flow 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 explains the confirmation requirement and the two distinct invocation paths: a client-supported prompt versus the two-step token fallback, including exactly when a repeat call is allowed and that the first call makes NO network call. It misses explicit when-not-to-use guidance or named alternatives, but the confirmation protocol is the central usage decision and it is fully specified.

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?

Even though annotations already declare readOnlyHint and idempotentHint, the description adds meaningful behavioral context: the data is cached and not a live fix, derived output only appears when coord.lat/coord.lon exist, and the raw fallback has unverified field names. This goes beyond what annotations convey and helps an agent set expectations about freshness and output variability.

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: the first states the data source, the second clarifies freshness and points to the refresh sibling, the third explains derived vs. raw output. No fluff or repetition of schema/annotation content.

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, single-optional-parameter tool, the description covers the essential context: data provenance, staleness, prerequisite action for recent data, output derivation rule, and the fallback behavior. There's no output schema, but the description itself sufficiently describes what the caller will receive.

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% — the sole optional vehicle_key parameter is fully described in the schema, including its default behavior for single-vehicle accounts. The tool description itself doesn't add parameter-level detail, so the baseline score of 3 is appropriate; there's nothing missing but also nothing extra to credit.

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 identifies the resource (the vehicle's last known location from the cached cmm/gvi read's `location` block) and explicitly contrasts it with a live GPS fix, which distinguishes it from any sibling that might report real-time data. It also names the source and the derived lat/lon/map-link output, leaving no ambiguity about what the tool does.

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 an explicit usage directive: run kia_refresh_status first for a recent location. It also implies that this tool is for cached last-known data rather than fresh data. It doesn't enumerate when not to use it or compare against kia_vehicle_status, but the context is clear enough for an agent to select it appropriately.

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 provide readOnly/idempotent/openWorld hints. The description adds substantial non-obvious behavior: cached data may be stale, syncDate advances on every read (so it never proves change), seat heatVentType/heatVentLevel encoding is UNVERIFIED, and an absent seat block does not mean the car lacks heated seats. This materially prevents misuse.

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

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

The description is long and dense, but it front-loads the core purpose ('CACHED status') and every sentence carries a caveat or clarification that prevents incorrect agent behavior. It could be trimmed slightly (e.g., the airTempRange/seatHeatCoolOption implementation detail), but the length is justified by the tool's complexity.

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?

With no output schema, the description carries the burden of explaining return semantics. It covers what fields appear, the meaning of absent climate/seat blocks, EV ignition naming, and what include_raw returns. It also addresses the freshness limitation and data reliability, making it complete for correct 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 description coverage is 100%, so the baseline is 3. The description adds value by elaborating on include_raw ('untrimmed status block (battery/EV detail, doors, tyres, …)'), which is not in the schema. It does not discuss vehicle_key further, but the schema already covers it.

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 ('Read the vehicle's CACHED status') and names the concrete fields (door lock, ignition, remote-climate block). It explicitly contrasts itself with kia_refresh_status by highlighting cached vs. fresh data, so an agent can distinguish siblings immediately.

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 when-to-use guidance: 'use kia_refresh_status first when freshness matters' names the alternative and the condition that selects it. It also instructs when to pass include_raw, and warns about interpreting seat data, making the call context 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?

Beyond the annotations, the description discloses important behavioral side effects: the remember-me token is stored locally and NOT returned, every Kia tool will silently refresh the session thereafter, and MFA is never needed again on this device. This is significant state-changing behavior that directly explains the destructiveHint annotation without contradicting it.

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

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

The description is compact but information-dense. It front-loads the primary purpose, then explains the critical side effects, and finally connects the parameters to their source. Every sentence earns its place with 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 state-changing authentication step with no output schema, the description is complete: it states the result (session established, token not returned), the side effects (silent refresh, MFA no longer needed), and the required inputs and their source. An agent has enough context to invoke it correctly and understand its consequences.

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 covers all parameters with 100% description coverage. The description adds value by explaining the origin and relationship of otpKey and xid to kia_start_login and clarifies that otp is the code the user received, which is beyond what the schema 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?

The description clearly states the tool's purpose with a specific verb and resource: 'exchange the passcode for a session' and identifies it as 'Step 3 of the Kia MFA bootstrap'. It also distinguishes the tool's role from siblings like kia_start_login and kia_session_status by describing its outcome.

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 for when to use the tool: after kia_start_login, using the otpKey and xid returned by that step, and after the user receives a code. It implies sequencing through 'Step 3' but does not explicitly state 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.