Submit a batch job

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

Annotations cover safety (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial context beyond them: cost model (free submit, 62 credits per photo, 93 for real-time singles), the 409 collection_not_writable refusal, the no-base64 constraint, and that unreachable URLs fail individually after submission. It does not explain the idempotency_key behavior, which the schema carries instead, and says nothing about batch size limits on concurrency or duplicate URL handling.

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 two ops, then cost, then error and result-access semantics. Dense but nearly every clause carries operational information; the parenthetical about the real-time 93 rate for a one-photo batch is a minor digression but relevant to cost decisions.

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 an asynchronous batch-submission tool with no output schema, the description covers the full lifecycle: submit, pay, poll or webhook, and read results per op. It also warns of the costly failure mode where op=match results are charged but unreadable without a webhook, which is exactly the information an agent needs before invoking.

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 earns an extra point by explaining the consequence of the op enum choice (faces stored vs matched photo ids delivered only via webhook) and by clarifying that photos must be URLs, not base64. It adds little for override or webhook_endpoint_id specifically, but the op semantics it supplies are genuinely load-bearing.

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 and resource ('Queue up to 1000 photo URLs for background processing') and immediately disambiguates the two modes, op=index vs op=match. It also differentiates itself from siblings by naming search_faces as the alternative for small jobs, so an agent can place it precisely in the toolset.

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 routing guidance: use search_faces for a few photos, poll get_batch or register a webhook for completion, read index results via get_batch_photos, and only use op=match when a webhook_endpoint_id is supplied. It states both when to use this tool and when to prefer another.

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