Consult Kimi (paid)

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

Discloses far beyond the annotations: the read-only agent profile (no shell/write tool), the static-review limitation ('treat findings as unvalidated claims you verify yourself'), data egress of question and extra_context to the provider, best-effort redaction that does not cover typed inputs or files Kimi reads, AGENTS.md auto-loading with skills that can point outside the workspace, and timeout termination with unrecoverable partial output. The readOnlyHint=false annotation is consistent — the tool is read-only for files but is PAID and makes external calls — so the description adds context without contradicting 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?

Front-loaded with purpose, then cost, safety, data flow, and recovery — each paragraph carries a distinct critical topic with no filler. It is long (~380 words), but the length is largely earned given 9 params, paid quota, and external egress; minor redundancy exists where the description restates schema-level isolation/redaction notes.

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 high-complexity tool (paid external call, 9 parameters, blocking timeout, async fallback, data egress), every operational concern is covered: preconditions, cost, safety profile, data handling, redaction limits, timeout/recovery, and when to route to the async sibling. The output schema covers return values, so the 'result envelope' mention suffices.

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

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

Schema coverage is 100% with rich per-parameter descriptions, so the baseline is 3; the description adds operational value on top: workspace_root targeting decision ('omit it for pure Q&A'), clamp/default semantics for timeout_seconds (10-600s, 300s default), isolation's non-suppression of built-ins/AGENTS.md, and redaction bounds for extra_context. It also cross-references kimi://params rather than duplicating full lifecycle details, which is appropriate.

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

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

Opens with a specific verb+resource: 'Ask Kimi (a different model) for a read-only second opinion or answer,' which pinpoints the tool's role as a cross-model consult and distinguishes it from every sibling (not status, not delegate, not review_changes). It further disambiguates from kimi_consult_async by framing this as the synchronous, paid variant.

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 preconditions and routing: 'run kimi_status (free) first to confirm the CLI is installed and authenticated,' and it states the no-dry-run limitation. For long or high-effort consults it names kimi_consult_async as the preferred alternative with concrete deadline numbers (300s vs 1800s), and provides a recovery chain via kimi_job_list/kimi_job_status/kimi_job_result. It also tells the caller when to pass workspace_root vs omit it.

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