batch_create_embeddings

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it's an async batch job (not immediate), mentions cost ('50% cheaper than standard API'), specifies the model and dimensions, and outlines the multi-step workflow. However, it doesn't mention rate limits, error handling, or job duration expectations.

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 well-structured with clear sections (COST, MODEL, WORKFLOW, TASK TYPES) and uses bullet-like numbering for the workflow. It's appropriately sized for a complex tool, though some sentences could be more concise (e.g., the workflow list is verbose but necessary).

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 batch processing tool with 6 parameters, 100% schema coverage, and no output schema, the description does a good job of providing context. It explains the async nature, cost benefits, model details, and full workflow. However, it doesn't describe the output format or error responses, which would be helpful given the lack of 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 the baseline is 3. The description adds some context: it mentions the model (gemini-embedding-001 with 1536 dimensions) and references batch_query_task_type for task type guidance, but doesn't provide additional parameter semantics beyond what's already in the schema descriptions.

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: 'CREATE EMBEDDINGS BATCH JOB - Create async embeddings generation batch job.' It specifies the exact action (create async batch job) and resource (embeddings), and distinguishes it from siblings like batch_ingest_embeddings (for content conversion) and batch_get_status (for monitoring).

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 workflow guidance: 'WORKFLOW: 1) Prepare content (use batch_ingest_embeddings for conversion), 2) Select task type (use batch_query_task_type if unsure), 3) Upload file, 4) Call batch_create_embeddings, 5) Monitor with batch_get_status, 6) Download with batch_download_results.' It names specific alternative tools for different steps and clarifies when to use them.

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