SightRadar MCP Server

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

With annotations covering only safety hints (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description adds real behavioral context the annotations cannot: exact credit pricing per input combination (186/93/93), the best-face selection rule, and null similarity when a side has no face. It omits auth/permission requirements and error conditions, which keeps it from a 5.

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 operation and its return contract, then inputs, then cost. Every sentence carries information; the three-case credit sentence is slightly verbose but the pricing per combination is genuinely decision-relevant.

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 naming the returned fields (face_found, similarity, match, threshold) and their null semantics. It leaves the threshold's origin and default unexplained, and says nothing about failure modes beyond a missing face, which is the main remaining gap for a paid comparison call.

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 meaning the schema does not: each side is one of three mutually exclusive forms (public URL, CDN key, or 512-number embedding). That explains why all seven parameters are optional — the caller picks one form per side — which the schema alone leaves ambiguous.

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 and resource: 'Check whether two images (or embeddings) show the same person', plus the key qualifier that it uses the best face on each side. An agent can distinguish this from search_faces, but the description never names or contrasts that sibling explicitly, so differentiation is inferred rather than stated.

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 context is implied by the operation itself (verify a 1:1 identity match) and the credit cost breakdown gives an economic reason to prefer embeddings, but there is no explicit when-to-use / when-not-to-use guidance and no mention of search_faces as the alternative for one-to-many lookups.

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?

Adds real behavior beyond the annotations: an existing active collection succeeds with no change, a deleting/deleted one returns 409, and the operation is free (no billing impact). The idempotency point partly overlaps idempotentHint and destructiveHint=false is not elaborated (what is destroyed on a 409 path), but the error semantics and cost disclosure are genuine value-adds.

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 compact sentences, front-loaded with the definition, then the idempotency/error behavior, then the optionality note and cost. Nothing is repeated and the 'Free.' fragment still carries actionable 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?

For a one-parameter create tool with annotations covering readOnly/destructive/idempotent hints, the description covers purpose, optionality, error behavior, and alternatives. The only gap is what a successful response contains, which is a minor omission given there is 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 coverage is 100% and the single parameter is fully documented in the schema, including naming constraints. The description's 'for example one per event' echoes the schema's own example, so it adds little new meaning; baseline 3 applies when the schema already 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 specific verb and resource ('Create a face collection'), gives a concrete use case ('for example one per event'), and implicitly distinguishes itself from restore_collection and recreate_collection by naming them as the alternatives in the conflict path. An agent can tell what this tool produces 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?

Goes well beyond a plain when-to-use: it says the call is optional because indexing into a missing collection also creates it, and it names restore_collection and recreate_collection for the 409/deleted case. Both the 'you may not need this' and 'here is the alternative when it fails' conditions are explicit.

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 declare the mutation profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true, idempotentHint=false), and the description adds real substance: the exact HMAC-SHA256 signature header formula, the timestamp component, which events are delivered, and the one-time secret disclosure that must be surfaced to the user. It does not cover delivery retry/failure behavior despite sibling tools like list_webhook_failures and replay_webhook_failures implying failures exist.

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 that front-load the purpose, then the signature contract, then the secret caveat. The signature formula is dense but earns its space; the trailing 'Free.' is a one-word pricing note that is mildly out of place but harmless.

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 2-parameter mutation tool with no output schema, the description supplies what the response actually yields (a one-time secret) and the verification contract the caller needs. The main remaining gap is behavior on duplicate registration and how failures are surfaced, given non-idempotent semantics.

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 params are already documented, but the description adds operational meaning beyond the schema: the generated secret is returned exactly once in this response and the user must store it, which materially changes how the agent handles the result. It also clarifies the URL must be public HTTPS, reinforcing the format constraint.

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 ('Register a public HTTPS URL to receive batch-completion and deletion events'), naming exactly which event classes trigger delivery. Combined with siblings list_webhooks and delete_webhook, an agent can immediately distinguish creating a hook from listing or removing one.

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 context is implied by the event types (subscribe to batch completion/deletion), but there is no explicit when-to-use or when-not guidance, and no reference to siblings such as list_webhooks to check for an existing registration before creating a duplicate. The agent must infer placement from the name and event 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 only declare destructive/idempotent/open-world; the description adds the soft-delete default, the 7-day grace period, when purging becomes irreversible, the GDPR/BIPA audit mode, and the confirmation refusal path. It also discloses that the operation costs no credits.

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?

Four tightly packed sentences, front-loaded with the destructive default and ending with the confirmation duty. Dense but nearly every clause carries decision-relevant information; the trailing 'Free.' is terse to the point of ambiguity.

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 destructive four-parameter tool with no output schema, the definition covers irreversibility, recoverability, refusal behaviour, and cost, leaving nothing an agent needs to call it safely.

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 goes beyond the schema by explaining how immediate and compliance interact with the refusal behaviour and by framing confirm_erase as a retry token rather than a plain flag.

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 and resource ('Delete a collection') and immediately scopes it to everything contained in it ('every face, selfie and photo record'), which distinguishes it from the sibling delete_photo.

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 restore path (restore_collection) and the window in which it works, contrasts three modes of deletion, and instructs the agent to confirm with the user before calling. It also tells the agent exactly how to recover from a confirmation_required response.

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 destructive/idempotent annotations by disclosing that deletion is soft by default, that immediate/compliance make it permanent, and that a nonexistent photo_id still returns deleted=true — a real behavioral trap the agent must guard against. The "Free" cost note is a bonus. Not quite a 5 only because it doesn't cover what data is retained in the soft-delete window.

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 action, then the default-vs-permanent distinction, then the idempotency caveat, then cost. Three dense sentences with no wasted words.

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 4-param destructive tool with no output schema, the description covers the action, reversibility, permanence modes, the false-positive return behavior, and cost — everything an agent needs to call it safely and report accurately.

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 meaning the schema lacks: it explains the default soft behavior and what immediate=true and compliance=true each do (permanent vs audited legal erasure). This genuinely extends the terse 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?

States a specific verb and resource ("Remove every face indexed from one photo"), scoping it to a single photo and clarifying it removes faces rather than the photo itself. This clearly separates it from siblings like restore_photo and delete_collection.

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 frames the soft-vs-permanent choice, naming restore_photo as the undo path for the default and identifying immediate=true/compliance=true as the permanent route. It doesn't compare against other deletion tools like delete_collection, but the within-tool 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?

The description goes beyond the annotations by explicitly stating the cost ('Free') and providing a detailed operational behavior (endpoints succeeding again after being disabled), which is more specific than the 'idempotentHint: true' annotation.

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 definition is extremely concise and efficient. Every phrase adds value—identifying the result, handling idempotency, and stating the cost—making it highly structured despite its brevity.

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 single-parameter mutation tool, the definition is highly complete. It covers the action, the mechanism of failure/idempotency, and operational constraints like cost.

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?

Given the schema description coverage is 100%, the description adds little semantic value to the input parameter itself. It serves more as a behavioral context setter, justifying the baseline score of 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?

The description clearly states the primary action: 'Stop deliveries to a webhook endpoint.' While similar to general 'disable' commands, the focus on deliveries anchors its purpose well within the webhook context.

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 definition provides a crucial usage guideline by mentioning that 'Already-disabled endpoints succeed again.' This informs the agent how to handle idempotency without needing to check the full idempotency hint or tool output.

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?

Adds real behavior beyond the annotations: nothing is persisted, each call costs 93 credits, and a quality gate can suppress faces from the count. The credit cost and non-storage guarantee are exactly the details an agent needs before deciding to call. The idempotency/409 semantics live in the schema, so nothing material is lost there.

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: capability, return shape, then use case plus cost. No repetition of the name or title and no filler; every clause carries information the agent would otherwise have to guess.

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, describing detected_face_count, gated_face_count and the per-face fields is genuinely necessary and is done well, and the credit cost is disclosed. The only gap is that the meaning of the quality gate (what min_px or quality_passed thresholds are) is unexplained, which matters for interpreting gated_face_count.

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%, and each of the five optional image-source parameters is fully documented in the schema, including size limits and source trade-offs. The description adds only the '(ratios)' note about bounding boxes, which is a return-value detail, not parameter guidance, so 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 and resource ('Find the faces in an image') plus the crucial distinction from its closest sibling: it does not store anything, unlike index_photo. The return payload and credit cost are named up front, so an agent knows exactly what this call produces.

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 a clear use case ('check a photo or selfie before indexing'), which implicitly routes the agent away from index_photo and toward this tool for a dry run. It stops short of naming index_photo or compare_faces as explicit alternatives, so the routing is inferred rather than stated.

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 establish readOnly, idempotent, non-destructive, and closed-world behavior, so the description's added value is the freshness claim ("real-time") plus the credit-to-USD conversion rate and per-operation costs. That is genuine context an agent cannot get from annotations or schema. It stops short of saying whether the balance is account-wide or per-key.

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, then dense pricing facts, with no filler sentences. The trailing fragment "Free." lacks a clear antecedent (which operation is free?), which slightly hurts precision.

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 zero-parameter read tool with no output schema, the description supplies what is needed to interpret the response: units and the 100,000-credits-per-dollar conversion. It does not state the returned field names or whether plan/quota info accompanies the number, but that is a minor gap for a tool this simple.

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 takes zero parameters, so the schema-coverage baseline is 4 and there is nothing for the description to compensate for. The pricing details are interpretive context for the result, not parameter meaning.

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 resource ("current credit balance of the account") and implicitly the read verb, which is unambiguous. It does not explicitly distinguish itself from the sibling get_usage, which likely returns consumption detail, so the sibling differentiation is left to inference.

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?

There is no explicit when-to-use statement or named alternative. However, the embedded per-operation pricing table implies the intended use case: checking affordability before costly operations like index, detect, or compare. Usage is implied rather than stated.

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 declare read-only, idempotent, non-destructive, closed-world behavior, so the safety bar is covered. The description adds genuinely new behavioral context: a hard cap of 5000 ids per call, and the important silent-filtering rule that ids you don't own are omitted rather than erroring. 'Free' also discloses that calls are not billed, which is not derivable from any structured field.

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 tight sentences with zero filler: return fields first, then the invocation modes and limits. Every clause carries information, and nothing is buried.

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, listing the returned fields in the description is exactly the right compensation, and the 5000-id cap plus ownership omission rule cover the main edge cases. Minor gaps remain around what is returned for ids that don't exist versus ids not owned, but the definition is sufficient to call the tool 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% and the maxItems=5000 constraint is already in the schema, so baseline would be 3. The description earns an extra point by documenting the one-vs-many mutual exclusivity and the ownership-filtering semantics, neither of which is expressed in the schema itself.

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 names a specific resource (batch jobs) and enumerates the returned fields (status, total_photos, succeeded, failed, pending), and explicitly covers both the single and bulk retrieval modes. It stops short of naming how it differs from siblings like list_batches or get_batch_photos, which is left to inference.

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?

'Pass batch_id for one, or batch_ids ... for many at once' gives clear parameter-selection guidance for the two modes. However, it offers no when-to-use framing against list_batches or get_batch_photos, and no prerequisites, so the routing decision between status-checking tools is only implied.

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 declare readOnly, idempotent and non-destructive, so the bar is lower. The description still adds genuine context: the exact payload fields including a failure reason_code, the paging mechanism, and that the call is free (no billing impact), which an agent cannot get from 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 short sentences with zero filler; the payload contents come first and the paging rule and cost note follow. 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 usefully compensates by naming the returned fields and explaining pagination. It does not enumerate possible status values or say what happens for photos still in flight, which is a modest remaining gap for a results-reading tool.

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% and every parameter is already documented, so the baseline applies. The description does reinforce the paging contract by tying after_index to next_after_index, but that is largely a restatement of the schema's own parameter description.

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 and resource ('Per-photo results of a batch') and enumerates the returned fields (external_id, status, face_count, reason_code), which lets an agent tell it apart from the batch-level get_batch and the mutation siblings. It stops short of naming those siblings explicitly.

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 only implied: an agent can infer this is the drill-down after submit_batch or get_batch, but the description never says when to call this versus get_batch or requeue_failed_batch_photos, and gives no prerequisites or exclusions.

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 declare readOnly, idempotent and non-destructive, so the safety profile is covered; the description adds non-obvious behavior on top: counters are cached by default, verify triggers a slower authoritative recount, purge_after appears only when a deletion is pending, and the call is free. These are exactly the traits an agent could not infer from the schema or 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?

Three short sentences, zero filler: what it returns first, the caching/verify trade-off second, cost last. Every clause carries information an agent needs, and the most important detail (default is cached) is positioned early.

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 correctly compensates by listing the returned fields, and it covers the caching caveat and cost. Remaining gaps are minor — the possible values of status and the behavior for a nonexistent or purged collection_id are not described.

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 both parameters are already documented and the baseline is 3. The description adds modest meaning for verify by contrasting it with the cached-counter default, but says nothing extra about collection_id beyond what the schema's format constraints already state.

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?

"Show one collection" pairs a specific verb with a specific resource and immediately enumerates the fields returned (status, photo_count, face_count, selfie_count, created_at, purge_after), so an agent knows exactly what it gets back. It is distinguishable from list_collections by the singular scope, though it never names that sibling explicitly.

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 gives one concrete decision rule — set verify=true to recount from the vector store instead of trusting cached counters — which is genuine when-to-use guidance for that parameter. It offers nothing on when to call this versus list_collections, get_deletion_status, or restore_collection, so the broader routing decision is left 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?

Annotations already establish readOnly, idempotent, non-destructive behavior, and the description adds genuinely new context beyond them: the full state machine (not_deleting through blocked), verified_zero, purge_after, retry attempts, last error, and that calls are free. The main gap is what happens when collection_id is unknown or never existed.

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?

One dense sentence, front-loaded with the verb and resource, then the returned fields in priority order. The trailing word 'Free' is slightly abrupt but is a useful cost signal and costs almost nothing.

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, so the description properly serves as the return-value documentation by listing phases and fields such as verified_zero, purge_after, attempts and last error. It is nearly complete for this complexity; only the unknown-collection outcome is unstated.

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?

There is a single parameter at 100% schema coverage, including a description and character restrictions, so the schema carries the load. The description adds no parameter-level meaning beyond that baseline.

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, 'Track a collection deletion', and enumerates the phase values, which makes it distinguishable from sibling delete_collection (which initiates) and restore_collection. It does not explicitly say 'read-only status polling', but the phase list makes the monitoring role clear.

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 monitoring role is implied by the phase enumeration, but there is no explicit when-to-use statement such as 'call after delete_collection to poll progress' and no mention of alternatives or when this is unnecessary. An agent must infer the workflow from 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 establish this as a read-only, idempotent, non-destructive, closed-world call, so the bar is lower. The description adds meaningful context beyond that: the call is free, and each granularity returns different content, including storage charges and stored-vector counts in the daily and storage modes.

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 the core resource statement front-loaded, followed by mode behavior and date-window syntax. Nothing is redundant and every sentence carries 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?

There is no output schema, so the description carries the burden of describing returns, and it does so per granularity (per-op totals, day-by-day series, vector counts and storage credits). It stops short of specifying response field names or pagination, but the essential shape is conveyed.

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 formats, min/max, and default notes already documented, so the baseline is 3. The description does add meaning for the enum, explaining what each granularity value actually returns, which goes modestly beyond the schema's terser 'Default summary.'

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 resource and measure: 'Calls and credits spent, per operation,' making clear this is a consumption-reporting tool. It does not explicitly name the closest sibling (get_balance) or distinguish itself from it, which keeps it short of a 5.

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 modes of use are implied through the granularity explanations, and the 'Free' note signals it costs nothing to call. However, there is no explicit when-to-use guidance or routing advice such as 'use get_balance for credit balance, get_usage for consumption breakdown,' so the agent must infer the division of labor.

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?

Rich disclosure beyond annotations: exact credit cost (93), the quality gate thresholds (det_score < 0.6 or <24 px), auto-creation of the missing collection, and the two named error codes already_indexed and photo_id_in_other_collection. It doesn't disclose rate limits or concurrency behavior, and the destructiveHint=false annotation is not directly addressed even though reuse of a shared photo_id can move faces out of another collection.

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 core action, then return values, quality gate, error semantics, id uniqueness, and cost in a tight sequence. Every sentence carries operational information an agent needs before calling.

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 8 parameters, no output schema, and a write operation, this description covers what it returns (point_id, bounding box ratios, detection score, pixel size), failure modes, side effects, and billing. Nothing material is missing for a correct call.

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 still adds genuine meaning by explaining that photo_id must be unique across all collections and that reuse can relocate faces or trigger photo_id_in_other_collection. The override and idempotency parameters are covered by the schema, so no further credit is warranted.

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 and resource — 'Detect every face in a photo and store them in a collection' — plus the downstream payoff (findable via search_faces). This clearly separates it from siblings like detect_faces (no storage) and search_faces (lookup only).

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 clear when-to-use context (index now so faces can be searched later) and when re-indexing is appropriate (override=true). It doesn't explicitly name detect_faces as the no-persist alternative, so the routing between the two detection tools is left partly 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral detail beyond that: result ordering (newest first), the exact summary fields returned, and the cursor-based forward pagination contract, plus the 'Free' cost signal. It does not say how far back 'recent' reaches or the retention window.

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 short sentences, front-loaded with purpose and payload, followed by the paging rule; the fragment 'Free.' earns its place as a cost signal. No redundant wording.

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 carries return-value duty and does so by naming the status and count fields as well as the next_* cursors. It is nearly complete for a simple paginated list tool; only the meaning of 'recent' and any page-size default are left to the 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%, including the cursor fields referencing next_before_id/next_before_created, so the baseline is 3. The description restates the same cursor contract rather than adding new meaning such as cursor expiry or interaction between the two cursor values.

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 and resource (list batch jobs), plus the ordering (newest first) and the payload (status and succeeded/failed/pending counts). This clearly separates it from the singular get_batch sibling, though it never names siblings explicitly.

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 explains the paging follow-up ('for the next page pass next_before_created and next_before_id from the previous answer') and notes the call is free, which is useful selection context. It gives no when-to-use versus get_batch/get_batch_photos guidance and no exclusions.

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 declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered; the description adds genuinely new context by noting the call is free (no credits consumed) and that results include photo/face/selfie counts. It still says nothing about result ordering or total-count/paging metadata, which is the remaining gap.

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 sentences with no waste: scope first, return contents second, capabilities and cost last. Nothing to trim.

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 simple, zero-required-parameter read tool with no output schema, the description covers scope, payload contents, filtering and cost adequately. Only result ordering and whether a total count is returned are left unstated.

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 every parameter (limit, query, offset, status) is already documented, and the description only echoes "substring search and paging." It notably does not say which field the query matches (the schema says collection id), leaving a mild ambiguity rather than adding meaning.

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 and resource ("List the face collections on this SightRadar account") and even names what each row carries (photo, face and selfie counts). It does not explicitly distinguish itself from the sibling get_collection, so an agent must infer the plural/singular split, but the purpose itself is 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?

"Supports substring search and paging" implies this is the browse/enumerate entry point versus get_collection for a single record, but that alternative is never named and no when-not-to-use condition is given. Usage is deducible rather than stated.

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 declare read-only, idempotent, non-destructive and closed-world, so the safety profile is covered. The description still adds meaningful behavior beyond that: the failure set is defined as retry-exhausted after exactly 9 attempts (not merely recent errors), the response fields are previewed, and 'Free' signals no credit cost. Pagination/ordering behavior is the only notable omission.

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?

A single tight sentence, front-loaded with the scope-defining clause ('gave up after all retries') followed by the return fields and the cost note. Every clause carries information; nothing is redundant.

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 listing the returned fields, and it defines the failure semantics and cost model. For a one-parameter read-only list tool this is close to sufficient; only result ordering and pagination beyond the limit cap are unaddressed.

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% and the sole limit parameter is fully documented there (default 50, max 200). The description adds nothing about limit and does not say whether results are ordered or capped in a particular way, so it sits at the baseline where the schema carries the parameter burden.

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 precisely which resource is listed: webhook deliveries that exhausted all retries, and enumerates the returned fields (delivery_id, endpoint, url, attempts, status code, error). 'Gave up after all retries (9 attempts)' sharply defines the failure set, implicitly distinguishing it from list_webhooks. It does not name sibling tools such as replay_webhook_failures, so differentiation is inferred rather than explicit.

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 only implied through the definition of 'failed' as terminal retry exhaustion, which usefully rules out in-flight or transiently failing deliveries. There is no explicit when-to-use statement, no mention of pairing with replay_webhook_failures to act on results, and no mention of list_webhooks as the broader alternative.

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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the returned field set and the 'Free' cost note, which is genuinely useful context not present in structured fields, but says nothing about ordering or pagination of the listing.

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, then the return fields, then the filter and cost. No filler and nothing redundant.

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 single-optional-parameter read tool with no output schema, the inline field list effectively documents the return shape and the 'Free' note clarifies billing impact. The only gap is whether the listing is complete or paged, which is not addressed.

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 status enum is documented in the schema itself, so the baseline is 3. The description confirms the filter is optional but adds no format or behavioral detail (e.g., default behavior when omitted) beyond what the schema already 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 gives a specific verb and resource ('List webhook endpoints') and enumerates the returned fields (id, url, status, created_at), so the agent knows exactly what it gets. It does not explicitly distinguish itself from the related sibling list_webhook_failures or create_webhook/delete_webhook, which keeps it out of the top band.

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?

'Optionally filter by status' tells the agent the filter is opt-in, which is implied usage guidance for the single parameter. There is no explicit when-to-use versus list_webhook_failures or when-not guidance, so selection still requires inference from the sibling names.

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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the agent knows the safety profile. The description adds two genuinely new facts — 'the old faces are not recovered' (so this is not a true undo) and 'Free' (no quota/credits consumed) — but says nothing about error behavior if the collection is not in deleted status, which is the main failure mode. The 'old faces are not recovered' line is not a contradiction of destructiveHint=false since the deletion already happened, though it does qualify the expectation.

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 sentences, front-loaded with the action and its precondition, followed by the two non-obvious caveats. Nothing is redundant and nothing could be cut without losing 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?

For a single-parameter, non-read-only tool with full schema coverage and rich annotations, the description covers the essentials: what state is required, what is and is not recovered, and the cost. Only the failure behavior when the precondition is unmet 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%, and the schema already documents collection_id with examples and allowed characters. The description only adds that the id must be the same one the purged collection had, which is mild reinforcement rather than new semantics. 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 and resource — bring back an empty collection under the same id after full deletion. The parenthetical '(status deleted)' carves out a precise scope that implicitly separates it from restore_collection, but the sibling is never named, so the agent must infer the distinction.

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 precondition (only after the collection is fully deleted / status deleted), which is the key usage gate for a 1-param tool. It stops short of naming restore_collection or create_collection as the alternatives for other states, leaving that routing 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?

Goes well beyond the annotations by disclosing cost (93 credits), the quality gate thresholds (det_score < 0.6, under 24 px) that cause an HTTP 422 and non-storage, and the no-face outcome. One wrinkle: the description says a retry with the same idempotency_key 'returns the original point_id', while the schema says such retries get a 409 duplicate_request_already_processed — a minor internal inconsistency about what actually comes back.

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?

Four tight sentences, front-loaded with purpose then return values then failure modes then cost. The idempotency sentence partially duplicates the idempotency_key schema description, which is the only real 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?

With no output schema, the description carries the return-value burden and does so for the main fields (face_found, point_id, embedding, reason=no_face) as well as the 422 quality-gate path. It omits other error shapes and any limits on collection size or per-user selfie counts, leaving modest gaps.

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 every parameter is already documented in the schema, including the idempotency_key retry semantics. The description adds essentially no new per-parameter meaning beyond restating the retry behavior, so the baseline of 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 and resource ('Store a user's selfie in a collection') plus the downstream purpose (matching against collection photos), so an agent knows exactly what it achieves. It does not explicitly contrast itself with the similar sibling index_photo, so it stops short of full sibling differentiation.

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 clear usage context (enrolling a selfie so it can later be matched) and routes the agent forward to search_by_point_id using the returned point_id. It also covers the retry case via idempotency_key. It never states when NOT to use it or why one would pick index_photo instead.

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 declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. The description adds genuinely new context — that it returns a requeued count and that the call is free — but says nothing about what actually happens on replay (retry of original payload, whether replayed deliveries can fail again, or any rate limits).

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?

Four short sentences, front-loaded with the action, then parameter behavior, then return value, then cost. Nothing is padded and each sentence 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 one optional parameter and no output schema, the description covers the essentials: what it does, how to scope it, and roughly what comes back. It is only missing post-replay expectations (do failures re-enter the failure list, are partial failures reported), which for a simple replay tool is a minor gap.

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% and the schema's own description already says "omit for all", so the description largely restates the parameter. It does emphasize the bulk consequence of omitting the field, which is a small value-add over the schema, but no format details (ID provenance, ordering, limits) are added.

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 ("Send failed deliveries again" / replay of failed webhook deliveries), which is concrete enough to distinguish it from the adjacent listing tool. It stops short of naming list_webhook_failures as the sibling that produces the IDs, so differentiation relies partly on the tool name.

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 explains the two modes of invocation (specific IDs vs. omit for all), which is practical usage guidance. However, it never states when to use this at all — no prerequisite such as "after list_webhook_failures", no caution about bulk replaying everything, and no alternatives named.

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?

Adds substantial behavior beyond annotations: preview_id expires after 10 minutes and is usable once, requeued photos are charged when processed, and the preview exposes exact per-photo and estimated credit costs. This gives the agent the safety and cost context needed before committing a mutation.

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 front-loaded with the core action and then explains the two-step flow, user confirmation, and cost in a compact sequence. Every sentence supports correct invocation, with no wasted 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?

Covers the critical preview workflow, preview_id constraints, and pricing well enough for a two-step mutation tool. Because there is no output schema, it could be more complete about what execute=true returns after requeueing, but the essential invocation details are present.

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 schema already documents all seven parameters. The description still adds meaningful workflow semantics for execute and preview_id, including preview validity and one-time use, though it does not elaborate on limit, date filters, or stagger_seconds beyond the schema.

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 and resource: retry failed batch photos for a given reason. The two-step preview/execute framing makes its purpose distinct from sibling tools like submit_batch or get_batch_photos.

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 instructs the agent to call first with execute=false, show the preview to the user, then call again with execute=true and the preview_id. It does not compare against alternative remediation tools, but the workflow guidance is clear enough to select and invoke it correctly.

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 declare non-destructive, idempotent, non-read-only behavior, and the description adds context annotations cannot express: the exact failure modes (purge started, compliance erasure) and the cost note ('Free'). It does not say what state the collection is returned in or whether membership/photos are preserved, which is the one meaningful gap.

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 sentences with zero filler: the operation and its window come first, then the failure conditions, then the cost note. Every clause carries information an agent would otherwise have to guess.

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 mutation with no output schema, the description covers preconditions, failure modes, and cost, which is most of what an agent needs. A brief note on the resulting state of the restored collection would close the remaining gap.

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?

There is a single parameter and the schema documents it fully (100% coverage, with format constraints and examples), so the schema carries the burden. The description adds no meaning about collection_id beyond what is already structured, which is the baseline case.

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 and resource ('Undo a soft delete' on a collection) plus the precondition that defines the operation, which separates it from delete_collection and get_collection. It does not explicitly distinguish itself from the sibling recreate_collection, which is the closest alternative, so it stops short of a 5.

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 both a positive condition (collection still in its grace period, status deletion_pending) and negative conditions (purge has started, compliance erasure), which is real when-to-use guidance. It never names an alternative tool such as recreate_collection for the post-purge case, so the routing advice is incomplete.

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 declare readOnlyHint=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered structurally. The description adds two pieces of context not in the annotations: that the deletion was 'soft' (implying recoverability rather than permanent loss) and that the call is 'Free', a meaningful cost signal given the presence of get_balance and get_usage siblings. It omits failure behavior, such as what happens if the photo is no longer restorable.

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 short sentences with zero filler; the purpose is front-loaded and the cost note is appended where it does not interrupt the main statement. Every clause earns its place.

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 two-parameter restore tool with full schema coverage and complete annotations, the description supplies purpose, the originating sibling, and cost. The only meaningful gap is the absence of any note about restore eligibility or time limits, which an agent might need when a restore fails.

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 (photo_id, collection_id) are documented in the schema, including the collection id format constraints. The description adds no meaning beyond that, so the baseline of 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?

The description states a specific verb ('Undo') and resource ('a soft photo deletion'), and names the sibling operation that created the state to be undone ('made with delete_photo'). An agent can distinguish this from restore_collection and recreate_collection without inspecting 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?

It gives clear when-to-use context by tying the tool to a prior delete_photo call, which is exactly the precondition an agent needs. It stops short of explicit exclusions or edge conditions (e.g. deletion window expiry, what to do if the photo was hard-deleted), so it is strong but not complete routing 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?

Adds important behavior beyond annotations: cost of 62 credits, return shape [{photo_id, score}], accepted point_id forms, and the point_not_found error for face point ids. Annotations already cover idempotency, openness, and non-destructiveness; the description adds the operational details an agent needs.

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?

Four compact sentences, front-loaded with the core purpose, then the cost comparison, ID constraints, return format, and price. Every sentence carries useful information and there is 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?

For a five-parameter search tool with full schema coverage and annotations, the description covers the essential gaps: cost, return format, accepted ID types, and the specific error case. No output schema exists, but the return shape is stated, so an agent has enough to call and interpret the 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?

Schema coverage is 100%, so the schema documents all parameters. The description still adds meaning for point_id by specifying it must come from register_selfie for this collection and by explaining the UUID/unsigned-integer forms and the failure mode for face point ids. It does not add further meaning for limit or threshold, but those are already documented in the schema.

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 and resource: find a registered person's photos using a stored point_id. It clearly distinguishes this from search_faces by being cheaper and from index_photo by rejecting face point ids. An agent can identify the exact operation 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?

Explicitly says when to use it: when you have the point_id returned by register_selfie and want to avoid resending the selfie. It also says when not to use it: face point ids from index_photo return reason=point_not_found. The alternative search_faces is named with a cost comparison.

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 the cost (93 credits), the return shape ({photo_id, score} best first, plus photo_ids), and the named failure reasons (no_face, low_quality_selfie). The annotations already flag openWorldHint and idempotentHint, and the description's cost disclosure usefully explains why readOnlyHint is false; only rate limits and the semantics of 'score' are left implicit.

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: what it does, what it returns, what failures mean, and what it costs — front-loaded with the core purpose and free of filler. Every clause carries distinct information an agent needs before calling.

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 carries the return contract itself and does so: match list shape, ordering, parallel photo_ids, and reason codes for empty results. Combined with the 100%-covered schema and the cost disclosure, nothing material 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 description coverage is 100%, so every parameter is already documented in the schema, including the embedding origin and the calibrated default for threshold. The description adds no syntax, format, or precedence guidance beyond what the schema already provides, so the baseline of 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 and resource with scope: find photos in a collection matching the person in a query image or a 512-number embedding. The 'in a collection' scoping separates it from a standalone face comparison, but it never names the neighboring tools (compare_faces, detect_faces, search_by_point_id) it should be distinguished from.

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 rather than stated: 'typically a selfie' hints at the common input, and the embedding path is described, but there is no explicit when-to-use vs. when-to-use-a-sibling guidance and no note on choosing among the five query modalities (file_path, image_url, gcs_key, image_base64, embedding).

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 (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.