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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description usefully reinforces it ('makes no changes') and adds real context the annotations cannot — that the values are verified against a live vehicle and that the payload is one entry per plug type (AC/DC). It does not mention auth/session prerequisites, but the added return-shape and live-verification detail is meaningful.

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 clauses, front-loaded with the verb and resource before the payload detail and the read-only reassurance. No filler sentences; 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?

With no output schema, the description partially compensates by describing the return contents (one entry per plug type for AC/DC). Combined with annotations covering read-only/open-world and a fully documented single parameter, an agent has enough to call it correctly, though field-level return detail and session/auth behavior remain implicit.

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% — vehicle_key is fully documented in the schema, including the crucial 'not the VIN' and 'never defaults to the only vehicle' notes. The description adds nothing about parameters, which is the expected baseline when the schema does the work.

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 precise verb and resource ('Read the EV charge targets') and names the underlying endpoint (`evc/gts`), then specifies exactly what is returned: target state of charge per plug type, one entry for AC and one for DC. This is clearly distinguishable from the mutation sibling kia_set_charge_limits and from the broader status 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?

Usage is implied by the framing ('Read the EV charge targets') and the closer 'Read-only — makes no changes' signals it is the inspection half of the charge-limit pair. However, it never explicitly says when to reach for this versus kia_set_charge_limits or kia_session_status, and gives no prerequisites beyond the schema.

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?

Goes well beyond the annotations by disclosing real-world side effects: it wakes the telematics unit, is much slower, draws power, and — critically — Kia only acknowledges the request with no completion signal and no returned data. That is exactly the kind of non-obvious behavior an agent would otherwise get wrong.

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 tight sentences, front-loaded with what the tool does and the cost of calling it, then the awkward acknowledgement-only behavior, then the required follow-up. 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?

There is no output schema, and the description compensates by explaining precisely what comes back (only an acknowledgement) and what the agent must do next. Combined with the scoping guidance and cost warning, an agent has everything needed 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?

Schema description coverage is 100% and the schema already documents vehicle_key including the single-vehicle default, so the description need not repeat it. The description adds no parameter-level detail of its own; 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?

Opens with a specific verb+resource ('ask the car for a fresh reading') and even names the underlying protocol call (rems/rvs, requestType 0). It explicitly positions itself against kia_vehicle_status, so the agent can distinguish the two without opening either 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?

Gives an explicit decision rule: 'prefer the cached read unless staleness matters,' naming the exact alternative tool and the condition that selects this one. It also instructs the follow-up read (kia_vehicle_status afterwards), leaving nothing 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?

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?

Annotations declare readOnlyHint=false, idempotentHint=true, destructiveHint=false, but the description adds substantial context beyond them: the write is verified by re-reading evc/gts and reporting whether it landed, the list REPLACES stored state (a destructive-in-effect REPLACE semantic that annotations don't capture), and the preview phase makes no network call at all. The confirmation behavior is fully disclosed.

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

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

Front-loaded with the core purpose and the verified-write fact, then the mutation-vs-replace warning, then the confirmation flow. Every sentence earns its place, though the confirmation section is dense and could be more skimmable.

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 a mutation tool with no output schema and complex two-phase confirmation, the description covers everything an agent needs: scope, replace semantics, verification, and the exact confirmation protocol including the preview/confirmToken fallback. 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%, so the baseline is 3. The description adds value by explaining the REPLACE semantics of the targets list and the two-phase confirmToken flow, which are not fully conveyed by the schema alone. It doesn't restate parameter syntax (the schema handles that), so it doesn't reach 5.

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 precise verb+resource: 'Set the target state of charge per plug type'. It also ties the write to the underlying evc/sts path, which distinguishes it from the read-side sibling kia_charge_targets (which reads evc/gts). An agent can differentiate this from kia_charge_targets without opening either 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?

Explicit guidance on when and how: 'Send BOTH plug types — the list replaces the stored one, so omitting an entry drops that target.' It also delineates the confirmation flow (client prompt vs two-step confirmToken fallback) and warns that the first call makes no network call. This is unusually thorough routing information.

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 cover safety (non-destructive, idempotent) but the description adds high-value behavior the annotations can't: silent no-op on unplugged vehicles, ~30-60s latency before evStatus.batteryCharge flips, and unreliable success status. It also explains the confirmation flow (preview + confirmToken, or elicitation). Minor gap: doesn't state auth/session requirements beyond the confirmation note.

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?

Front-loaded with purpose and the API endpoint, then verification conditions and confirmation flow. Dense but well-organized; the confirmation paragraph is slightly long but justified by a non-obvious two-phase behavior.

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

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

Covers the mutation's non-obvious risks (silent no-op, flaky success signal) and the async confirmation mechanism, which is the main thing an agent could get wrong. A note on auth/session prerequisites would complete it, but it is otherwise complete for a 3-param write tool with no output schema.

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

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

Schema description coverage is 100%, so vehicle_key, chargeRatio (10-100, default 100), and confirmToken are already fully documented in the schema. The description mentions confirmToken behavior, which is the schema's own text, so it adds no new semantic detail. Baseline 3.

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

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

Specific verb+resource ('start charging') with the underlying API endpoint named (evc/charge), which distinguishes it cleanly from kia_stop_charge and kia_set_charge_limits.

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

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

Explicit prerequisites (car must be plugged in, and that an unplugged car silently no-ops), plus explicit routing: confirm via kia_vehicle_status rather than trusting success.

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?

Goes far beyond the annotations: discloses the 30–60s state-change lag, that commandAccepted and stateConfirmed are distinct, that waitSeconds can outlast a client timeout and report false failure, that the confirmable two-step preview makes no network call, and that seat/steering/rear-window heating are deliberately omitted. Annotations only cover safety hints, so this context is highly valuable.

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?

Front-loads the purpose and confirmation flow, but the final sentence about omitted heating fields is long and the doc-reference caveats accrete. Most sentences earn their place, though it leans dense with parenthetical asides.

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

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

Covers everything needed to invoke correctly: confirmation mechanics, polling behavior, timeout pitfalls, misleading field names (no flat airCtrlOn, ign3 as ignition proxy on EVs), and the best-effort temperature caveat. No output schema exists, and the description adequately describes what to expect back.

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 already 100%, so the baseline is 3, but the description adds real meaning the schema lacks: temperature is best-effort/unconfirmed (70°F read back as 72°F), waitSeconds can outlive a client timeout and the correct recovery is re-reading status rather than re-sending, and confirmToken must only be passed after explicit user approval. It doesn't re-explain vehicle_key, which the schema already covers.

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?

Names the specific verb+resource (start remote climate control / preconditioning) and pins it to the Kia rems/start endpoint. It is unambiguous against siblings like kia_stop_climate, and it names the nested field (climate.airCtrl) that defines success.

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?

Explains the confirmation flow and how to proceed when a client lacks elicitation (preview + confirmToken then repeat). It doesn't explicitly compare against kia_stop_climate or state when the user would want climate preconditioning versus charging, but the operational when-to-use guidance is clear.

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

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

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?

Goes well beyond the annotations: documents the observed latency (~30-60s until evStatus.batteryCharge flips false), warns that the success status is not trustworthy, and explains the two-phase confirmation fallback where the first call makes NO network call. The idempotent/destructive hints are consistent with this narrative.

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?

Front-loaded with the action and endpoint, then layered verification and confirmation detail. Dense but every sentence carries new information; only slight length cost from the parenthetical about MCP_CONFIRM_MODE.

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

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

No output schema exists, so the description must cover return behavior, and it does: it describes the phase-1 'confirmation-required' preview plus confirmToken and the eventual charging state change. An agent has everything needed to call and verify 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 both parameters (vehicle_key, confirmToken) are already thoroughly documented in the schema. The description restates the confirmToken flow and the MCP_CONFIRM_MODE mechanism, which adds framing but little syntax the schema lacks; 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+resource ('Ask the vehicle to stop charging') and even names the underlying endpoint (`evc/cancel`). It is unambiguously distinguishable from the sibling kia_start_charge / kia_start_climate 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?

Gives explicit post-call guidance: verify with kia_vehicle_status instead of trusting the success status, and it spells out when the confirmation prompt applies and how the no-elicitation fallback works. It does not explicitly contrast with start_charge, but the operational context is clear enough to act on.

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 cover the safety profile (non-destructive, idempotent, open-world), but the description goes well beyond: the confirm-gating behavior, the distinction between commandAccepted and stateConfirmed, the nested climate.airCtrl field vs. the non-existent airCtrlOn, the ign3 EV ignition proxy, and the observed 30–60s state-change latency.

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?

It's a dense paragraph but every sentence carries operational weight: confirmation flow, field names, accepted-vs-confirmed distinction, and timing. It is front-loaded with the core action and endpoint. Slightly long, but no filler sentences.

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?

Although there is no output schema, the description supplies the critical post-command behavior (re-reading cmm/gvi, nested airCtrl field, commandAccepted vs stateConfirmed) and latency that an agent needs to interpret results correctly. Nothing essential for correct invocation 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%, so the baseline is 3, but the description adds real meaning: confirmToken is only for the fallback flow and must never be reused or invented, and waitSeconds relates to the 30–60s observed propagation. The parameter semantics are reinforced rather than merely repeated.

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' — names the exact Kia endpoint (rems/stop), and implicitly distinguishes itself from the sibling kia_start_climate. An agent can identify the tool's job 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?

It clearly explains when the confirmation flow applies: elicitation clients get a prompt, others get a no-network preview plus confirmToken, and a repeat call is required. It doesn't explicitly contrast with kia_start_climate or failure-recovery alternatives, but the confirm-mode branching is thorough contextual 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 only cover readOnly/openWorld/idempotent, but the description adds real behavioral context beyond them: data provenance (cached cmm/gvi read), staleness, the conditional derivation path when coord.lat/coord.lon exist, the raw-block fallback, and an honest caveat that the raw block's field names are unverified.

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 with no filler, and the most decision-relevant fact (cached, not live) is front-loaded. It is a bit long for a one-parameter read tool, but every clause adds distinct information.

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

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

No output schema exists, so the description must explain return values - and it does, covering both the derived lat/lon plus map link case and the raw-block fallback, including the uncertainty about field names. Nothing an agent needs to interpret the result 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% and vehicle_key is fully documented in the schema (including the single-vehicle default), so the description carries no additional parameter information. Baseline 3 applies when the schema does the heavy lifting.

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 precise verb+resource - returns the vehicle's last known location - and immediately scopes it as coming from the cached cmm/gvi read rather than a live GPS fix. This distinguishes it from kia_refresh_status and the other status siblings without needing to open any 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?

Explicitly names the alternative (kia_refresh_status) and the condition that selects it ('run kia_refresh_status first for a recent one'), plus the freshness caveat that defines when this cached tool is appropriate. An agent has a clear routing rule.

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 declare readOnly/idempotent/openWorld, but the description goes far beyond: cache-staleness semantics, why climate may be absent rather than off, EV ignition naming (ign3 vs engine), the fact that syncDate never proves change, and an explicit warning that seat heat/vent encoding is UNVERIFIED. This is unusually rich operational context that prevents wrong agent inferences.

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?

Dense but front-loaded: purpose and the freshness caveat come first, then the domain caveats. Every sentence carries distinct operational value with no filler, though the paragraph is long and could be split for scanability.

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 and a complex automotive domain, the description compensates thoroughly, explaining return-field semantics (climate, ign3, syncDate, climate.seats) and their absence conditions. An agent has everything needed to call it and interpret results 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%, setting a baseline of 3. The description earns above-baseline credit by expanding what include_raw actually returns (battery/EV detail, doors, tyres) and by noting vehicle_key can be passed implicitly, adding meaning beyond the terse schema strings.

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 ('Read the vehicle's CACHED status') and enumerates the exact surface (door lock, ignition, remote-climate block). It explicitly distinguishes itself from the sibling kia_refresh_status, so an agent can route without opening a 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?

Gives an explicit when-to-use ('Fast') alongside the condition that selects the alternative ('use kia_refresh_status first when freshness matters'). The stale-data caveat functions as a clear when-not, and the include_raw hint maps to a usage decision.

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.