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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses critical behaviors: atomicity for validation errors, the risk that an ambiguous timeout/5xx may still commit, absence of duplicate detection, no auto-retry, and the requirement to verify via list_contacts. This is exactly the non-obvious behavior an agent needs before invoking a batch write.

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 sentences, each earning its place: what the call does/scales to, the return shape, atomicity and ambiguity handling, and the sequential-send/quota guidance. The most decision-relevant facts are front-loaded and no schema content is repeated verbatim.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex batch-write tool with no output schema, the description is complete: it names the return array and resourceName, explains failure semantics and retry safety, addresses duplicate creation, and covers quota/concurrency. An agent has enough to invoke it correctly and to recover from the API's ambiguous failure mode.

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

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

Schema description coverage is 100%, so the baseline is 3; the description adds value by saying the entries use the same normalized fields as create_contact and that each entry needs at least one field, which the schema does not explicitly require for the item objects. This helps agents compose valid contacts parameter 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?

The opening sentence states a specific verb ('Creates'), resource ('contacts'), upper bound ('up to 200 in one call'), and the underlying API. It also links entry fields to create_contact, distinguishing this bulk creation tool from single-contact siblings such as create_contact and batch_update_contacts.

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 clearly defines the batch's scope (up to 200 contacts per call) and gives operational directives: re-check via list_contacts after an ambiguous failure and never send mutate batches in parallel. It does not explicitly state 'use create_contact for exactly one contact,' but the 'same normalized fields as create_contact' comparison plus title makes the bulk-vs-single distinction recoverable.

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 declare destructiveHint=true and idempotentHint=false, and the description meaningfully expands on these: no undo, permanent deletion, empty result on success, atomicity per request, never auto-retried, and the NOT_FOUND outcome on a re-send after a committed delete. This substantially clarifies runtime behavior beyond what annotations alone convey.

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, each earning its place: the first states scope and permanence, the second gives the required precondition and finality, and the third explains failure recovery. It is front-loaded with the core behavior and contains 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 one parameter, no output schema, and destructive/idempotent behavior, the description covers all important operational aspects: batch limit, preconditions, return value, atomicity, retry guidance, and post-failure verification. Nothing an agent needs to safely invoke this tool 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%, with the resource_names property already fully documented including format, pattern, min/max, examples, and exact source. The description adds the contextual note to enumerate resource names first, but does not need to repeat param semantics because the schema is comprehensive.

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 ('Permanently deletes'), the resource ('contacts'), the exact scale ('up to 500 contacts in one call'), and maps to the underlying API ('People API people:batchDeleteContacts'). It is clearly distinguished from the sibling delete_contact by the batch scope.

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 gives explicit when-to-use guidance: list resource names first, use batch_get_contacts to confirm identities, and treat the call as final. It also prescribes exactly how to handle ambiguous failures—checking existing contacts instead of re-sending—which is strong usage guidance beyond a generic 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?

Beyond the readOnly/idempotent annotations, the description discloses ordering guarantees, per-entry response shape, NOT_FOUND handling instead of whole-call failure, and the requirement to check per-entry status. This is exactly the operational detail 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?

Three dense sentences deliver the core behavior, quota rationale, response format, and per-entry error handling without filler. The most decision-relevant information is front-loaded.

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 present, the description supplies a complete mental model of the return value, error semantics, ordering, and field behavior. An agent can invoke it confidently without inspecting other tools.

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 already 100%, and the description adds useful parametric context: person_fields behaves exactly as in get_contact and responses are returned in the same order as requested resource_names. These are meaningful additions beyond the schema's field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Fetches up to 200 contacts in one call'), identifies the underlying People API operation, and clearly distinguishes batch_get_contacts from the get_contact loop. The title and description together make its scope obvious.

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 explicitly frames the tool as the cheaper alternative to a get_contact loop under tight per-user quota, giving an agent a clear selection rule for batch retrieval. The comparison to get_contact is the needed routing guidance relative to siblings.

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 annotations, the description discloses critical behavior: the shared update-mask union, the clearing of omitted field groups, auto-fetching missing etags with an extra batchGet, atomicity per request, and whole-batch failure on stale etags. This is exactly the kind of non-obvious behavior an agent needs to avoid dangerous mistakes. No contradiction with annotations.

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

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

The description is dense but every sentence carries load-bearing information. It front-loads the core capability, then uses a CAUTION marker to highlight the dangerous shared-mask behavior, and closes with a concrete failure/recovery rule. There is no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the limit, the etag semantics, the destructive clearing behavior, atomicity, the 400 failure mode, and a deliberate retry strategy. Given the annotations and rich schema, nothing essential for correct invocation is missing. The lack of an output schema is not a significant gap because the primary risks are all disclosed.

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?

Although the schema documents each field, the description adds essential batch-level semantics: the update mask is shared across entries, a field group omitted by one entry but provided by another is cleared, and each provided group replaces its stored group as a whole. It also clarifies the optional etag behavior and the safe pattern of giving every entry the same fields. This significantly exceeds schema-only information.

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 exactly what the tool does: "Updates up to 200 contacts in one call" and identifies the underlying API. It clearly distinguishes itself from the singular update_contact by emphasizing batch scope and by referencing "the same normalized fields as update_contact." The verb, resource, and scale are all 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?

The description gives clear context: use this when updating many contacts at once, up to 200. It references update_contact for field semantics, which helps an agent understand the relationship, but it does not explicitly state "for a single contact, use update_contact" or list exclusions. The usage is strongly implied but not fully spelled out.

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: it explains that the operation returns the new saved person, that the original otherContacts entry remains, that duplicate executions create duplicates, and that two OAuth scopes are required. These are critical behavioral details not present in the boolean hints alone.

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?

Every sentence earns its place: the core operation, field-selection behavior, return-value guidance, side effects, duplicate risk, and scopes are packed into a compact but information-dense description. The key action is front-loaded.

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 mutation tool with no output schema, the description covers the input source, the mask semantics, the return value's resourceName, the non-destructive nature, the idempotency caveat, and required permissions. Agents have enough context to invoke it 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 schema descriptions already explain defaults and allowed values. The description adds marginal value by restating the copy_mask default and the resource_name source, but it does not explain read_mask beyond what the schema provides, so it meets the baseline but does not exceed 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 ('Copies'), a precise source ('Other contact'), and a destination ('user's saved contacts'), and explicitly identifies this as 'the only write that exists for Other contacts.' This clearly distinguishes it from siblings like list_other_contacts and create_contact.

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?

Directly tells the agent when to use this tool by declaring it is the only write operation for Other contacts, and gives the source via 'from list_other_contacts.' It also describes the copy_mask selection fields and duplicate behavior, providing actionable when-to-use 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 declare non-readOnly, non-idempotent, non-destructive, and open-world. The description enhances this by detailing the lack of duplicate detection, the never auto-retry policy, the eventual consistency for search indexing, and the photo limitation. These behavioral details go beyond what annotations convey and help the agent anticipate side effects.

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 dense but every sentence carries operational value. It is front-loaded with the purpose and return object, then systematically covers required fields, failure handling, indexing delay, and photos. Slightly long but not padded; could be trimmed without loss, but structure is sound.

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 tool with 14 parameters (nested objects) and no output schema, the description covers all essential operational aspects: return values, required-field rule, duplicate risk, failure strategy, indexing behavior, and photo limitation. It fully equips an agent to call correctly and handle edge cases.

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 adds meaningful constraints not in the schema: 'at least one is required' and the default person_fields mask, plus the clarification that an absent field may be unmasked. This goes beyond simple restatement.

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 'Creates a new contact in the account's Google Contacts and returns the created Person' — a specific verb and resource, clearly distinguishing it from update_contact, list_contacts, and sibling tools. It names the return object and its fields, leaving no ambiguity about the tool's intent.

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 explicit when-to-use guidance: states the requirement of at least one field, warns against auto-retry on ambiguous failures, instructs to verify via search/list before re-sending, and notes the indexing delay for search_contacts. It also names the photo-related alternative (raw_request with updateContactPhoto), providing clear routing among siblings.

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 discloses important non-obvious behavior: duplicate names fail with 409 CONFLICT instead of creating a second group, and the response includes resourceName, name, and etag. This adds value beyond the annotations by explaining idempotency failure, uniqueness enforcement, and return payload.

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 compact and front-loaded, with every sentence contributing useful information. It states the action, the return format, the uniqueness constraint, and the next logical step in three sentences without 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?

For a single-parameter creation tool with no output schema, the description is complete: it covers what is created, the return value, an important error behavior, and the follow-up tool. An agent has enough information to call this tool correctly and understand the outcome.

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 name parameter's uniqueness is already documented in the schema. The description reinforces the uniqueness rule and adds the specific 409 failure mode, but it does not need to add more since the schema already captures the 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 description states a specific verb and resource: it creates a new user contact group (label) and returns it. It also clarifies the resource identifier format, which distinguishes it from sibling tools like create_contact and list_contact_groups.

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 clearly indicates when this tool is appropriate: when a new contact group is needed. It also provides a pointer to modify_group_members for populating the group, giving useful workflow context. It does not explicitly exclude alternatives such as create_contact, but the purpose is unambiguous.

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 permanence, no API-level undo, the Google Contacts 30-day trash caveat, empty success return, and the non-idempotent failure mode where a retry after a timeout may hit 404. This fully aligns with destructiveHint=true and idempotentHint=false.

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?

Every sentence earns its place: irreversibility, verification step, return behavior, and failure handling. The core action is front-loaded, and the added detail is dense rather than padded.

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 single-parameter tool with no output schema, the description covers return value, preconditions, irreversibility, and recovery from ambiguous failures. Nothing essential for correct invocation 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%, with resource_name already fully described including pattern, example, and how to obtain it. The description adds verification guidance but no new parameter semantics, so baseline 3 is appropriate.

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: 'Permanently deletes one contact from the account's Google Contacts.' The phrase 'one contact' distinguishes it from the batch sibling while the resource 'contact' distinguishes it from delete_contact_group.

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 procedural guidance: verify resource_name with get_contact before deleting, and check with get_contact after ambiguous failures before retrying. It does not explicitly name alternatives like batch_delete_contacts, but the 'one contact' scoping makes the primary use 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 annotations already signal destructive=true, non-readonly, and non-idempotent, and the description substantially enriches that: contacts survive by default, delete_contacts=true permanently deletes all members, there is no undo, and the return is an empty result. This fully discloses the destructive 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?

Two focused sentences with the primary action front-loaded, followed by the crucial caveat and a practical pre-check. Every sentence earns its place, and the high-risk warning is placed immediately after the parameter mention.

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 tool with no output schema, the description covers return behavior, irreversibility, system-group restrictions, member survival semantics, and how to verify the roster before mass deletion. Nothing essential for correct invocation 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 description coverage is 100%, so the schema already documents both parameters well. The description adds a warning layer around delete_contacts and the default survival behavior, which is useful, but it does not introduce new meaning beyond what the schema provides.

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 precise verb-resource pairing: 'Permanently deletes a user contact group (label).' It further distinguishes group deletion from member deletion, clarifies that it applies to user groups, and notes that system groups cannot be deleted, which separates it from sibling tools.

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 explicitly states when the dangerous delete_contacts=true option should be used ('only when that is explicitly wanted') and provides a safer alternative action: check the roster first via get_contact_group. It also gives a firm exclusion: 'System groups cannot be deleted.'

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 cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is its behavioral contract: the etag is what update_contact needs for safe optimistic updates, memberships surface as contactGroups/<id> resource names, and the return shape (resourceName, etag, requested person_fields) is disclosed. This goes beyond the annotations without contradicting them.

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 no filler: sentence 1 states the operation and its two valid inputs, sentence 2 specifies the return envelope and defaults, sentence 3 ties the output to downstream tool contracts (update_contact etag, group memberships). Every sentence earns its place and the main verb is front-loaded.

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 carries the burden of explaining the return value (Person with resourceName, etag, person_fields) and the field-mask default behavior. The openWorldHint and schema caveat cover unknown-fields behavior. The only notable omission is error behavior for unknown or malformed resource names, which is a minor gap for a read tool whose safety profile is fully annotated.

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%: resource_name has a pattern plus a provenance hint, and person_fields has a full enum, minItems, and the critical 'absent field may be unmasked, not empty' caveat. The tool description only restates the default field list (names, emailAddresses, phoneNumbers, organizations, memberships), which the schema already captures. This lands at the baseline for high schema coverage.

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+resource+method combination: 'Fetches one contact by resource name', and clarifies the two accepted forms ('people/c...' or 'people/me'). The single-contact scope distinguishes it from list_contacts, batch_get_contacts, and search_contacts without needing to open any sibling 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?

The description establishes clear usage context: use when you have a specific resource name, including the special 'people/me' self-profile case. The schema's resource_name description reinforces this by stating the name must come 'exactly as returned by list_contacts, search_contacts or create_contact', and the etag note points forward to update_contact. However, there is no explicit exclusion such as 'for multiple contacts use batch_get_contacts instead', so routing guidance 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?

Beyond the readOnly/idempotent annotations, it discloses the conditional behavior of max_members, the format of memberResourceNames as people/<id> resource names, and the significance of the etag for safe renames. This is useful operational detail that annotations alone do not convey.

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 well-structured sentences pack in return fields, member behavior, cross-tool routing, and etag semantics without redundancy. The most important action and resource appear first, and every phrase 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?

Given the rich annotations and fully described schema, the description adds the missing behavioral and workflow context: what members look like, how to get their details, and how the etag is used downstream. No critical gap remains for an agent to select and invoke 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%, so the baseline is 3, but the description adds meaning by explaining that max_members controls whether members are included and by sourcing resource_name from list_contact_groups. It also ties the etag to update_contact_group, which is not evident from the schema alone.

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?

Description opens with a specific verb and resource: "Fetches one contact group by resource name," then concretely enumerates the fields returned. It also distinguishes itself from sibling tools by calling out that this is the only way to get group members and that the etag feeds update_contact_group.

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 gives clear context: use this tool to fetch a single group and especially to obtain member resource names, since that is the only way the API returns them. It points to batch_get_contacts and update_contact_group as follow-up tools, though it does not explicitly state when to prefer list_contact_groups over this tool.

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 readOnlyHint and idempotentHint annotations, the description discloses important behavior: the return envelope, the distinction between user-created and system-fixed groups, default group_fields behavior, page_size limits, and sync_token expiration semantics (410). This gives an agent a strong model of what will happen.

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 dense sentences cover return format, group taxonomy, field defaults, pagination, and sync behavior without fluff. Key information is front-loaded (what is returned), and every sentence 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?

With no output schema, the description fully compensates by enumerating the response fields and edge cases. It covers pagination, sync tokens, group types, and field customization, leaving little for an agent to guess.

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 already 100%, but the description adds substantial value beyond the schema. It explains the default group_fields, warns that memberCount must be explicitly included if narrowing fields, and clarifies page_size limits and sync_token expiration behavior. This is more than the schema alone provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists the account's contact groups and specifies the exact response fields (contactGroups[], resourceName, name, groupType, memberCount, nextPageToken, totalItems). It also distinguishes the two group kinds (USER_CONTACT_GROUP vs SYSTEM_CONTACT_GROUP), which sets it apart from related siblings like get_contact_group or list_contacts.

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 verb 'Lists' makes the primary use case obvious, and the description adds useful context about when you would care about member counts or sync tokens. It references list_contacts for sync_token behavior but does not explicitly state when to choose this tool over siblings like get_contact_group or list_contacts, so it falls short of 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 mark this as read-only, idempotent, and non-destructive, and the description adds substantial behavioral context: absent person_fields may be unmasked rather than empty, deleted people carry metadata.deleted=true, sync tokens expire after ~7 days with HTTP 410, and pagination behavior is described. No contradiction with annotations.

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

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

The description is dense but appropriately sized for a complex listing tool with no output schema. It is front-loaded with the core purpose, then covers pagination, incremental sync, error behavior, and exclusions without 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?

With no output schema, the description fully explains the return structure: connections[], resourceName, etag, person_fields, nextPageToken, totalItems, and nextSyncToken. It also covers pagination, sync token usage, expiration errors, and scope exclusions, making it complete 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 coverage is 100%, so the schema already documents each parameter. The description still adds meaningful semantics beyond the schema, such as default person_fields, absent-field masking behavior, sync token expiry, and pagination flow. It does not add new detail for sort_order, but the schema already covers that.

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: 'Lists the account's saved contacts (People API people/me/connections)'. It also distinguishes itself from siblings by explicitly excluding the Workspace directory and auto-saved addresses, pointing to list_other_contacts.

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?

Clearly defines when this tool is appropriate: for the user's own saved contacts, and explicitly says it is not for the Workspace directory or auto-saved addresses, naming the sibling alternative. It also explains when to use incremental sync via sync_token and request_sync_token.

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 the description reinforces them ('Other contacts are read-only') while adding substantial behavior beyond the annotations: the automatic warmup request before the first search, prefix-match search capped at 30 with no pagination, sync-token 410 failure semantics, and the OAuth scope requirement with the 403 diagnostic. No contradiction with annotations.

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

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

The description is dense but every sentence is functional — the core definition and sibling distinction are front-loaded, followed by modes, field set, edit path, and auth. It is a single long paragraph that could be structured with clearer separation between the search and list modes, but there is no filler or repetition.

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-mode tool with pagination, sync tokens, auth requirements, and no output schema, the description is complete: it covers the returnable field set, error semantics (410, 403), the automatic warmup, scope requirements, and the editing pathway. An agent has everything needed to invoke and interpret this 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%, so the baseline is 3, but the description adds genuine cross-parameter meaning: setting query invalidates page_token and sync tokens, search caps at 30 results while listing allows up to 1000, and read_mask default fields are stated. The description explains interactions and error semantics the per-property schema cannot express, though each individual parameter is already well 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?

The description opens with a specific verb-resource pair ('Lists Other contacts') and immediately defines what Other contacts are: addresses Google auto-saved from email interactions. It explicitly distinguishes the tool from siblings by stating Other contacts are NOT in the saved contact list and never appear in list_contacts/search_contacts. An agent can tell exactly what this tool does and how it differs from its nearest 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?

Usage guidance is explicit: the description names list_contacts/search_contacts as the tools that will NOT return these contacts, and names copy_other_contact as the required path for editing. It also spells out the two invocation modes — search with a query vs. paginated listing with tokens — and warns that expired sync tokens fail with 410, directing re-listing in full. This leaves no ambiguity about when to call this tool and how.

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 well beyond the annotations by explaining that HTTP 200 is not a full success receipt and that notFoundResourceNames and canNotRemoveLastContactGroupResourceNames identify skipped changes. It also discloses convergence on re-run and the non-deletion guarantee, which is especially valuable given destructiveHint is true.

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 then packs each sentence with non-redundant information: batch capability, resource-name addressing, response caveats, idempotency, and the myContacts exclusion. There is no filler or repetition of schema content.

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 must and does carry the burden of explaining the response semantics and edge cases. It covers partial failures, skipped contacts, the last-group protection, convergence, and non-destructiveness, making the tool's behavior predictable even without an 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?

Even though schema coverage is 100%, the description adds critical semantics the schema does not: at least one of add/remove must be provided, the combined limit is about 1000 names, and resource names follow people/<id> format contextually. It also adds the behavioral caveat about the myContacts group, which is parameter-relevant for remove.

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 the exact operation: adding and/or removing contacts in a contact group (label) in one call. It clearly distinguishes this from group-metadata operations like update_contact_group by focusing on membership changes, and even notes the myContacts exception.

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 the tool's purpose and the conditions for use clear: at least one of add/remove is required, and up to ~1000 names can be processed. It also gives an explicit when-not case by stating contacts cannot be removed from contactGroups/myContacts this way, and clarifies that removing a contact is not deletion, which helps route deletion intent to delete_contact.

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 annotations, the description discloses that the Bearer token is added automatically, the method defaults to GET, query strings and repeated parameters are supported inline, and writes are never retried after ambiguous failures. These are meaningful behavioral facts that neither the annotations nor the input schema provide, and they are consistent with destructiveHint=true and idempotentHint=false.

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?

Despite its length, the description is dense and every sentence earns its place: it states purpose, gives concrete endpoint examples, clarifies auth/defaults, and adds a retry caveat. The purpose is front-loaded and the examples are directly actionable.

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 arbitrary raw API tool, the description covers path construction, query-string handling, body usage, default method, auth token behavior, and write retry behavior. No output schema exists, but the raw response is implied by the tool name and title; nothing essential for invoking 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 100%, so the schema already documents all three parameters. The description adds extra value by explaining path query-string syntax, inline repeated parameters, and giving realistic path/body examples for PATCH and DELETE. This goes beyond the schema's basic descriptions without being redundant.

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 action ('call any Google People API v1 path directly') on a specific resource, and explicitly frames the tool as an escape hatch for requests the typed tools don't cover. This makes it clearly distinguishable from the sibling typed tools such as get_contact or list_contacts.

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 says exactly when to use it: when the typed tools don't cover a request, with concrete examples such as PATCH/DELETE contact photos, GET otherContacts with readMask, and extra query parameters like sources. The alternatives are the typed sibling tools, and the condition for choosing this tool is 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds substantial non-obvious behavior beyond the annotations: max 30 results with no pagination, server-side index lag of seconds to minutes, the automatic cache-warmup request, and the scope restriction to own saved contacts. These are exactly the behavioral traits an agent cannot infer from 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?

Four sentences, each earning its place: purpose and scope, return shape, result limits with sibling routing, and the index-lag caveat. The most decision-relevant facts are front-loaded. The cache-warmup parenthetical is detailed but preempts a predictable agent question about missing fresh contacts, so no sentence is wasted.

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 quick-lookup tool with no output schema, the description is complete: it covers return shape (results[] of { person } with read_mask fields), hard limits (max 30, no pagination), freshness caveats (index lag, warmup), scope (own contacts only), and the alternative for enumeration. No critical information an agent needs to invoke 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 description coverage is 100%, so the baseline is 3; the schema already documents query, page_size bounds, defaults, and the read_mask enum with its absent-field caveat. The description adds genuine value by specifying which fields the query prefix-matches (names, nicknames, emails, phones, organizations), which the schema's query description does not enumerate. This helps an agent construct effective queries but is a modest increment over an already-complete 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?

The description states a specific verb ('searches'), a precise resource ('the account's saved contacts'), and the matching semantics ('prefix match on names, nicknames, emails, phones and organizations'). It differentiates from siblings by scope ('Searches only the user's own saved contacts') and explicitly frames itself as a quick lookup rather than an enumeration, so an agent can distinguish it from list_contacts, get_contact, and list_other_contacts without inspecting schemas.

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 explicitly names the alternative and the condition that selects it: 'use list_contacts to enumerate everything.' It also gives when-not-to-use guidance by disclosing the search-index lag, telling the agent that contacts just created/updated may be invisible here even though list_contacts and get_contact already see them. This effectively routes the agent to the correct sibling based on recency of writes.

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 (destructiveHint=true, openWorldHint=true) by disclosing replace-as-a-whole semantics, empty-value clearing conventions, silent data loss risk, etag-conflict behavior (HTTP 400), and last-write-wins fallback. This is exactly the behavioral nuance needed to avoid destructive mistakes in an update operation.

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 purpose and packs essential warnings into dense, purposeful clauses. Three sentences carry a lot of critical information, and while the parenthetical density makes it somewhat hard to parse, every sentence earns its place given the tool's destructive potential.

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 16-parameter, nested-object mutation with no output schema, the description covers the essential decision points: prerequisite fetching, complete-group requirements, etag strategy, and the minimum-field constraint. Combined with the rich per-parameter schema descriptions, an agent has enough information to invoke this tool correctly and avoid silent data loss.

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 descriptions already cover each parameter at 100%, but the description adds a unifying semantic layer: group replacement rules, empty-value clearing, and the critical 'At least one contact field is required' constraint that is not evident from the schema's required array (which only lists resource_name). The etag behavior is also clarified beyond the schema note with failure mode details.

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 — 'Updates an existing contact and returns the updated Person.' This clearly distinguishes it from sibling tools like get_contact, create_contact, delete_contact, and batch_update_contacts by focusing on single-contact modification. The title and description align perfectly.

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 to fetch current values with get_contact first and send complete groups, or data is silently dropped — a concrete when-to-use rule with a referenced alternative. It also explains the two etag strategies (pass from get_contact or auto-fetch). It doesn't explicitly contrast with batch_update_contacts for multi-contact updates, but the single-vs-batch distinction is inferable from the tool 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 indicate this is a mutation (readOnlyHint=false, destructiveHint=true). The description adds valuable behavioral detail: etag-based concurrency handling with auto-fetch fallback, rejection of system groups, and uniqueness enforcement causing 409. It also states the return value. No contradiction with annotations.

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

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

Three dense sentences: the first states the core action and scope, the second explains etag behavior, the third covers limitations and the result. No redundant phrases; all sentences carry essential information. Front-loaded with the primary purpose.

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 mutation with concurrency, system-group restrictions, and uniqueness constraints, the description covers all critical aspects: behavior, edtag options, failure modes (409), and return value. No output schema exists, but the return is stated. Minor gaps like other error codes (e.g., 404) are acceptable given the specificity.

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 covers all 3 parameters with descriptions, including the etag 'omit to auto-fetch' note. The description repeats this etag guidance but adds no new parametric meaning. Since schema coverage is 100%, the baseline of 3 is appropriate; the description does not compensate beyond 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?

The description opens with a specific verb and resource: 'Renames a user contact group'. It also states the scope ('the only mutable group attribute'), which clearly distinguishes it from create/delete/modify operations. While no sibling is named, the uniqueness of the action 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?

The description provides clear context on when to use the tool: it's for renaming, and it explicitly warns that system groups cannot be renamed, implying alternative handling. It also explains the etag strategy (pass to avoid concurrent overwrites, omit for auto-fetch) and uniqueness constraint. It does not explicitly contrast with create/delete tools, but the purpose is obvious.

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