ContactZapp

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the authorization rule that any live key may invoke it and the shape of what comes back. However, it says nothing about what happens with an invalid or revoked key (error vs. empty result), which is the main behavioral question a caller testing a key would have.

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 no filler; the return payload comes first and the usage trigger second. Nothing is repeated from the title or schema.

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 burden of describing return values and does so in one clause. The remaining gap is failure semantics for an invalid key, which matters for a tool whose stated purpose is validating keys.

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 there is no parameter meaning to convey and the baseline of 4 applies. The description correctly focuses its words on return content instead of inventing parameter detail.

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 concrete return payload (acting user, plan, key scopes) so an agent knows this is an identity/introspection call rather than a mutation. It is clearly distinct from the unrelated siblings (contact_*, event_list, sync_start), though it never explicitly contrasts itself with them.

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?

"Call it to test a key" gives a direct usage trigger, and "Any live key can call it" establishes the access precondition. No alternatives are named, but none of the listed siblings offer overlapping functionality, so the guidance is effectively complete.

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 past the readOnlyHint=false / destructiveHint=true annotations: it discloses fan-out to every two-way account but never read-only ones, that history attributes the change to the user and names the API key, the 409 pending-review block, and retry safety via Idempotency-Key. These are exactly the side effects an agent cannot infer from structured fields.

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 paragraphs, front-loaded with the edit semantics and then ordered by consequence (scope, history, error, retry). Dense but every paragraph carries usable information; only the opening UI analogy is slightly expendable.

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 nested-body mutation with no output schema, it covers side effects, error behavior, and idempotency well. The main gap is that it never says what the successful response contains (the updated contact, or nothing), which an agent may need after the 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 description coverage is 100%, so the schema already carries detailed meaning for `id`, `body` fields, clearing semantics, and `Idempotency-Key`. The description's partial-update rule is valuable but largely duplicates the `body` schema text, so it adds little beyond the structured data.

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?

"Changes a contact, as editing it in ContactZapp does" gives a specific verb and resource, and immediately distinguishes it from contact_create and contact_read by anchoring it to editing an existing record. The first sentence alone lets an agent route correctly among the siblings.

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 clearly establishes the partial-update contract ("Only the fields you send change") and the blocking condition (a contact pending Review duplicates returns 409 `contact_pending_review`), plus when to attach an Idempotency-Key. What's missing is an explicit pointer to contact_create for new contacts, but the verb makes the split obvious.

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?

It discloses substantial behavior beyond the annotations: Auto-Merge may add values to an existing contact, each 200/201 outcome is explained, possible duplicates enter review, and the storage account and subsequent sync behavior are specified. It also explains that over-limit contacts are retained frozen without syncing and recommends an idempotency key for safe retries, exposing important side effects and operational consequences.

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 front-loads the core action and possible outcomes, using bullets effectively for the merge/create branches. The following short paragraphs each cover a distinct, consequential behavior, and the final retry sentence is concise; there is no filler despite the density.

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?

Combined with the fully documented nested schema, the description supplies enough context to invoke a complex create operation correctly, and its status outcomes are especially useful because there is no output schema. Minor gaps remain around explicit sibling routing, what happens when no eligible two-way account exists, and the response payload beyond the named statuses and `contact.frozen`.

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 schema already thoroughly documents the body fields, update/clearing semantics, and idempotency-key behavior. The description's recommendation to send `Idempotency-Key` on retries is useful operational emphasis but largely repeats the schema; most other description text concerns operation-level behavior rather than additional 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?

The opening "Adds a contact" states a clear verb and resource, while the `merged`, `created`, and `needs_review` outcomes clarify that the operation does not always produce a new record. It does not explicitly distinguish this tool from the sibling `contact_change`, so sibling differentiation remains incomplete.

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 practical context for creation, automatic merging, duplicate review, account selection, plan-limit handling, and safe retries. It does not state when not to use the tool or direct updates to `contact_change` and lookups to `contact_find`, but the intended creation context is otherwise 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?

Annotations already declare readOnly/non-destructive, and the description adds real value beyond them: deleted and merged contacts are never returned, results are newest-first by default, and pagination is cursor-based with the last page lacking `nextCursor`. Return shape is described only at a high level (no field list), 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 core action, then a bulleted per-parameter breakdown, then pagination rules. Every sentence carries distinct information with no repetition of the schema.

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 read-only search tool with no output schema and no required parameters, it covers matching semantics, default behavior, exclusion rules, ordering, and the full pagination loop. Nothing an agent needs to call it correctly 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 only 40%, but the description compensates fully for the undocumented parameters: `email` is case-insensitive, `phone` matches regardless of formatting, `query` mirrors the Contacts screen search, and `cursor` must be the prior page's `nextCursor` with the same filter. Only `limit` is left to the schema, which already documents it.

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 ('Finds the user's contacts') plus the exact matching keys (email, phone, query). This clearly separates it from contact_read (single-contact lookup) and contact_change/create without needing to name them.

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 constrains usage: 'Give at most one of email, phone and query' and explains the no-argument behavior ('every contact is listed, newest first'). It doesn't route the agent to sibling tools like contact_read for direct ID lookups, so not a full 5.

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 a safe read operation, and the description adds real value on top: deleted or merged contacts return 404, and another user's contact also returns 404, which tells the agent that access is owner-scoped and that not-found masks permission. It stops short of saying whether the 404 is distinguishable or what the returned object contains.

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 what is returned, followed by the identifier contract and the failure modes. No redundant restatement of the title or annotations.

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 read tool this covers the identifier formats and the failure semantics, which is most of what an agent needs. With no output schema, the description could have sketched the returned contact's shape, but the gap is minor for a standard lookup.

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 0%, so the description carries the burden for the single parameter, and it does: `id` accepts either the internal id or the publicId formatted like `CS-0042`. That is meaningful format guidance absent from the schema, though it does not clarify whether the two forms are interchangeable in all cases.

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?

"Returns one contact" gives a specific verb and resource with an explicit singular scope, which implicitly separates it from the list-style sibling contact_find. It never names contact_find or contact_change, so differentiation is left to inference 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?

The description makes clear this is the single-record lookup keyed by an identifier, but it never says when to prefer it over contact_find (search by other criteria) or contact_change (mutate). Usage is implied by the required `id` rather than stated as 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?

Beyond the supplied readOnlyHint/destructiveHint, the description discloses the key behavioral contract: ids are stable across polls, and new items arrive on top so consumers must dedupe. It also discloses retention differences per event family (History-backed events versus match.needs_review, whose id changes when flagged again), which directly affects polling logic.

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 one-line purpose, then a poll/dedupe paragraph, then two scoped bullet lists for event families and item payloads. Every section is load-bearing, though "what an automation needs, with no second call" is slightly promotional phrasing rather than specification.

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 mostly discharges it: item id stability, null contact fields after deletion/merge, absorbed-contact ids, and account attention reasons. It stops short of naming the concrete payload fields or the response envelope, leaving the exact shape partly unspecified for a tool an automation will parse.

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 real meaning beyond the enum descriptions: retention lifetime for History-sourced events and the id-instability of match.needs_review. It says nothing extra about limit or cursor beyond what the schema already documents.

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?

"Lists the events of one type, newest first" gives a specific verb, resource and ordering in the first sentence, and the polling-automation framing makes the tool's role unmistakable. None of the siblings (contact_*, sync_start, api_key_check) overlap with event retrieval, so the agent can route here without ambiguity.

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 states the intended usage pattern concretely: poll repeatedly, keep the ids you have seen, skip the rest, and use cursor to read further back. It does not name a when-not-to-use case or point at an alternative tool for other needs, which keeps it short of a 5.

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 say it is a non-read-only, non-destructive mutation, which is thin for a write-ish operation. The description adds real behavioral context: it is recorded in history as a manual run, it returns HTTP 202 with state 'queued' or 'running', and it is idempotent while a sync is in flight. It does not mention permissions or failure modes, so it stops short of full transparency.

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, each carrying distinct information: purpose, side effect on history, and return/state behavior. Purpose is front-loaded 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?

With no output schema, the description usefully explains the response (202 plus state value) and the no-duplicate-start behavior. Given a zero-parameter, no-output-schema tool, this is nearly complete; only error/failure behavior is left implicit.

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 there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no inputs are required.

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 ('Starts a sync') and anchors it to a known UI action ('the same as Sync now in ContactZapp'), so the agent knows exactly what operation this is. No sibling tool in the list covers sync, so the operation is unambiguous within 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?

The description implies a clear trigger condition (the agent wants a sync to run) and explicitly resolves the main alternative scenario: if a sync is already running, you get that one back instead of starting a second. There is no explicit when-not guidance or prerequisite statement, but the deduplication note covers the most likely ambiguity.

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