auto_annotate_start

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

The description goes far beyond the annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false) by disclosing that the operation is state-changing and billable, requires confirm_cost, has no cost preview, and may return 402. It explains that only explicitly set parameters are sent, server defaults apply otherwise, class_mapping passes through with no length check, labels are additive, a dataset version is snapshotted, billing settles at run time, and auto_annotate_stop does not refund. This is exceptionally transparent and adds substantial value beyond the structured metadata. No contradiction with annotations.

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

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

Though long, every sentence carries essential information: cost implications, parameter behavior, defaults, class_mapping purpose, additivity, versioning, billing timing, and status/cancel pointers. The structure is logical—core action, cost, parameter semantics, behavioral nuances, and lifecycle management. There is no fluff; each clause earns its place. The density is justified given 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?

The description covers the majority of what an agent needs: reference formats, cost and confirmation, parameter defaults and omissions, class_mapping usage, additive labeling, version snapshotting, billing timing, and related tools. However, it does not specify the return value or output format—there is no output schema, and the description never states what the tool returns (e.g., a run ID) that auto_annotate_status would poll. This is a minor gap given the tool's complexity, but it prevents a perfect score.

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

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

Schema description coverage is 100%, so the schema already documents each parameter's type and basic purpose. The description adds meaningful context: it explains the confirm_cost requirement, that only modelId and optionally confidence, iou, class_mapping, and include_annotated are sent (others omitted for server defaults), and that class_mapping bridges taxonomy mismatches with no length check. This goes beyond the schema's descriptive text, giving the agent operational semantics. It does not restate every parameter but adds value where nuance matters.

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 clear, specific verb-resource pairing: 'Start an auto-annotation run on a dataset... labelling it with a model...'. It explicitly lists the three accepted reference formats for both dataset and model, and differentiates from siblings by naming auto_annotate_status and auto_annotate_stop as the polling/cancelling counterparts. This is unambiguous and distinguishes the tool from its related operations.

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

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

The description provides explicit when-to-use guidance: it mandates confirm_cost=true, explains how to gauge cost magnitude via datasets_get, and warns about insufficient-credit 402 errors. It also states when to use alternatives: 'Use auto_annotate_status to poll and auto_annotate_stop to cancel.' It clarifies that no overwrite confirmation is needed because labels are additive, and explicitly notes the absence of an imgsz parameter, preventing misuse. This is comprehensive and actionable.

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