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

Annotations indicate a state-changing operation (readOnlyHint false). The description goes beyond the annotations by disclosing that adding attendees places the event on their calendars, and that emails are only sent when send_updates is set. It also explains an important API quirk (exclusive end date for all-day events). This adds behavioral context that the annotations alone do not provide.

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 three sentences with zero fluff. It front-loads the primary action ('Create an event') and then packs the critical nuances (date formats, exclusive end, attendee/email behavior) into compact, useful clauses. Each sentence earns its place; no redundant or vague phrasing.

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 11-parameter tool with no output schema, the description covers the key gotchas: timed vs. all-day handling, date-exclusivity, attendee calendar placement, and send_updates default. It does not mention the return value, but that is acceptable given no output schema. It omits no critical information that an agent needs to call 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 each parameter already has a description. The description adds value by clarifying the difference between timed ISO 8601 offsets and plain dates for all-day events, and by explaining the exclusive end-date behavior. It also notes the side effect of attendee emailing tied to send_updates. This goes beyond the schema's literal param descriptions, so a 4 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?

The description opens with the specific action 'Create an event,' which is a clear verb + resource. It further distinguishes the tool's purpose by detailing the two valid input formats (timed vs. all-day), which are unique to creating an event. This makes it unambiguous against sibling tools like calendar_update_event or calendar_delete_event.

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 usage context: when to use timed vs. all-day formats, how to set attendees, and the effect of send_updates. It does not explicitly name alternatives (e.g., use calendar_update_event to modify) but the create/update distinction is implied by the verb. It provides situational guidance without excluding alternatives, which earns a 4 rather than 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?

Goes well beyond the annotations by disclosing that deletion is IRREVERSIBLE with no undo or bin, and that the event is read before deletion so the answer indicates what was removed. The destructiveHint annotation is reinforced with concrete behavioral consequences, adding real value.

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 sentences with no wasted words. The critical irreversibility warning is front-loaded, followed by the pre-read behavior and the invocation condition. 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?

For a destructive tool with 4 parameters and no output schema, the description covers the essential behavioral context: irreversibility, what the response will indicate, and the condition for calling. Combined with the annotations and fully documented schema, nothing critical 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 fully documents all four parameters. The description does not add parameter-specific detail beyond the schema, which is acceptable and earns the baseline score.

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 an event.' The action is unambiguous and distinct from sibling tools like calendar_update_event or calendar_get_event. The first sentence directly matches the title, leaving no doubt about what the tool does.

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?

Provides clear usage context: 'Only do this when the user has clearly asked for it.' This is an explicit condition for invocation, especially important for a destructive action. It does not name alternatives or when-not-to-use scenarios, but the guidance is sufficient and 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 readOnlyHint and idempotentHint, but the description adds crucial behavior beyond them: if any calendar is unreadable, NO slots are returned and 'incomplete' is set, preventing double-bookings. It also discloses the timezone default-and-echo behavior, which is valuable operational context.

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 three sentences with no filler: the first states the core function, the second gives hard input constraints, and the third highlights a critical safety behavior. The IMPORTANT warning is front-loaded enough to prevent misuse.

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 core behavior, defaults, working-hours constraints, and failure semantics, while parameter details are fully present in the schema. The only meaningful omission is a precise description of the successful output structure beyond 'gaps' and 'incomplete,' but the annotation suite and schema make this a fairly complete definition.

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 beyond the schema by emphasizing that time_min/time_max must carry an explicit UTC offset and by revealing the timezone default (server zone) plus the echo behavior, which the schema does not specify.

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 precise verb+resource combination: find gaps that are free on EVERY account within working hours. This clearly differentiates the tool from event-listing siblings like calendar_list_events or calendar_get_event by emphasizing cross-account availability search.

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 implies when to use the tool: when you need common free time across multiple accounts within working hours. It does not explicitly name an alternative or state a when-not-to-use condition, but the context is strong enough for an agent to select it over the event-centric calendar 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?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive behavior. The description adds useful return-content context by specifying exactly what is included in a full event read, which is valuable because no output schema is provided. 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?

One crisp sentence that front-loads the action and resource, then enumerates the relevant return contents without any filler or 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 simple read operation with annotations covering safety and idempotency, the description and schema together are sufficient. The only minor gap is that the exact response shape is not fully specified, but the description's enumeration of returned fields largely compensates for the absent output schema.

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

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

Schema description coverage is 100%, with sensible descriptions for account, event_id, and calendar_id including the default for calendar_id. The tool description adds no parameter-specific details, but the baseline of 3 is appropriate since the schema already carries that 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 uses a specific verb ('Read') and resource ('one event') and clearly defines scope: description, location, attendees and their responses, and a link. This distinguishes it from calendar_list_events and other calendar operations 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?

The description implies the correct use case: retrieving the full content of a single event rather than a summary list or a mutation. It does not explicitly name alternatives like calendar_list_events, but the 'one event in full' framing gives clear contextual guidance with no exclusions needed.

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 this read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond those hints: recurrence expansion, cross-account merging and sorting, and the explicit UTC-offset requirement for timestamps. It does not contradict any 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?

Three sentences, each earning its place: the core action, the cross-account behavior, and the two critical gotchas (recurrence expansion and UTC offsets). The most important behavioral details are front-loaded and there is no redundant 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 read-only listing tool with 100% schema coverage and helpful annotations, the description covers the essential operational nuances an agent needs: time-range usage, account omission behavior, recurrence handling, and timestamp format requirements. The absence of an output schema is mitigated by the clear 'list events' framing.

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 mostly reinforces what the schema already says about 'account' and time parameters, though it adds the merged-and-sorted behavior and the recurrence-expansion detail. This is useful but does not substantially enhance parameter-level meaning 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?

The description states a specific verb and resource: 'List events in a time range,' with concrete behavioral details like merging all calendars, sorting by start time, and expanding repeating events. This clearly distinguishes it from sibling tools such as calendar_get_event, which targets a single event, and calendar_find_free_time, which searches availability.

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 contextual usage guidance: it explains how to query across every connected calendar by omitting 'account' and emphasizes the required time-range format with UTC offsets. It does not explicitly name alternatives or exclusion conditions, so it stops short of a full when-to-use versus when-not-to-use guide.

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 annotation set says the tool is not read-only and is idempotent, but the description goes beyond annotations by disclosing a crucial behavioral nuance: the update is partial, and passing attendees replaces the full guest list. It also explains why start and end must be paired. This adds real value beyond the structured data.

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 entire description is three sentences with zero filler. The most important fact ('only the fields you give are touched') is front-loaded, and the start/end pairing and attendee replacement exceptions are stated precisely without redundant elaboration.

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 12 parameters, the description covers the critical behaviors that could cause incorrect parameter usage: partial updates, paired temporal fields, and attendee list replacement. The remaining parameters are adequately documented by the complete schema, and no output schema is expected for an update operation. It is comprehensive enough without being verbose.

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 input schema covers all 12 parameters with 100% coverage, so the baseline is 3. The description adds cross-parameter meaning: the partial-update behavior for all fields and the attendee replacement semantics. While some of this is echoed in the schema, the description frames it as tool-level behavior, which is useful.

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?

Begins with a specific verb-plus-resource statement ('Change an existing event'), clearly distinguishing this from calendar_create_event and calendar_delete_event. It also adds partial-update semantics ('Only the fields you give are touched'), which sharpens what the tool does.

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 establishes the context for use — modifying an existing event — and adds important constraints such as start/end pairing and attendee replacement. It does not explicitly name sibling alternatives or state when not to use it, but the usage context is concrete enough for an agent to select it.

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 signal a write operation (readOnlyHint=false) and non-idempotency (idempotentHint=false). The description adds concrete behavioral context beyond that: Google performs no duplicate check, so repeated calls create duplicate contacts, and 'at least one field is required' states an input constraint. This enriches what annotations alone provide.

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 terse sentences, each earning its place: the core action, the required-input constraint, and the duplicate warning. The most important information is front-loaded and 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?

For an 8-parameter write tool with no output schema, the description covers the key operational risks (duplicates, minimum fields) and the schema documents every parameter with 100% coverage. The only minor gap is that it does not address account context or the return value, but for a create action with no output schema this is acceptable.

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 one genuinely new semantic rule not derivable from the schema: despite only 'account' being formally required, at least one additional contact field must be supplied. This cross-parameter constraint adds value beyond the JSON 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 action and resource: 'Add a person to the account address book.' It also scopes the tool to the 'account' address book, which combined with the sibling names (contacts_search, contacts_get, contacts_list, contacts_update) clearly distinguishes creation from the other contact operations.

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 guidance: 'Google does not check for duplicates — search first if the person might already be there.' This tells the agent to consult search before creating, which is clear when-to-use context. It does not name the sibling tool (contacts_search) explicitly, but the directive is actionable and sufficient.

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, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by specifying the return contents (every email, phone, label, organisation, job title, postal addresses, links, notes), which is behaviorally relevant and not repeated in annotations. It does not contradict 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?

The description is a single, tightly written sentence. It is front-loaded with the core purpose ('Read one contact in full') and then efficiently lists the return fields. There is no filler, and every phrase contributes useful 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?

Given the tool's simplicity (2 parameters, no output schema), the description covers what is needed: it explains the scope ('in full') and the specific fields returned. It does not list error conditions or explicitly state the absence of side effects, but annotations already cover safety, and the field list is adequate for an agent to understand the returned data. Overall, it is sufficiently 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?

The input schema provides full descriptions for both parameters (account and resource_name), and the schema coverage is 100%. The description does not add additional parameter-level meaning beyond what the schema already states (e.g., it does not clarify the 'full' return structure or the role of each parameter). Per the baseline rule for high schema coverage, a 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?

The description states the action explicitly ('Read one contact in full') and enumerates the specific data fields returned (emails, phones, labels, organisation, job title, addresses, links, notes). This clearly distinguishes it from sibling tools like contacts_search (which searches) and contacts_list (which lists), making the tool's purpose 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 implies usage: for a single known contact, use this tool. However, it does not explicitly state when to prefer it over contacts_search or contacts_list, nor does it mention any exclusions or prerequisites (e.g., that a resource_name is required). The guidance is implicit rather than explicit, so it falls short of a 4.

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; the description adds behavioral detail beyond that: ordering by most recently changed and the token-based pagination contract. It does not cover rate limits or auth, but those are not essential given the annotations and the account parameter.

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 core behavior, then token mechanics, then the sibling alternative. No filler or redundant clauses.

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 paged list tool, the description plus high-coverage schema and annotations is enough to invoke correctly. It covers ordering, pagination, and the search alternative; the absent output schema is not a blocker because the return shape is not needed to make 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 coverage is 100%, so account, page_size, and page_token are already documented. The description mainly reinforces the page_token round-trip, which is already in the schema, so it adds little parameter meaning beyond the 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 identifies a specific action (paging through the address book) and resource (account address book), and adds the sort order. It also names contacts_search as the sibling for targeted lookup, so an agent can differentiate the tools without opening 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?

It explicitly states when to prefer contacts_search ('looking for someone in particular'), implying contacts_list is for browsing or enumerating contacts. It also frames the pagination workflow, making clear this is the paging 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 read-only/idempotent annotations, the description discloses that the same person can be returned twice across accounts, that each copy has its own id and address book, and that merging would break a later contacts_update. This is exactly the kind of non-obvious behavior an agent needs to safely use the results.

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 sentences with no filler: the first states the purpose and matching behavior, the second explains the account-scoping option, and the third delivers the critical duplicate-result caveat. Each sentence earns its place and the most important usage detail 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 low-complexity read-only search with rich annotations and fully documented parameters, the description covers the core scenarios, the all-accounts exception, and the dangerous edge case around duplicates. No output schema is present, but the description provides enough return-related context (duplicate copies with distinct ids) to avoid misuse.

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 schema already documents all three parameters with descriptions, so the baseline is 3. The description adds meaningful semantic detail: query covers nicknames and organisations, omitting account triggers a global search, and max results are per account when searching all. This exceeds 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?

The description opens with a specific verb and resource ('Find people in the account address book') and enumerates the fields the query matches (names, nicknames, email addresses, phone numbers and organisations), so an agent can tell this is a query-based search rather than a plain list or fetch. It doesn't explicitly compare against sibling tools such as contacts_list or contacts_get, so it stops short of a top score.

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 concrete scoping guidance: omit 'account' to search every connected address book at once, and it warns that duplicates across accounts are intentional and that merging them would make contacts_update edit the wrong record. It does not state explicit when-not-to-use rules or name alternatives, but the context 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?

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description goes far beyond these: it warns that named fields are REPLACED not merged, advises reading the contact first, and explains the optimistic concurrency mechanism. No contradiction with annotations; it adds critical behavioral context.

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 a single well-organized paragraph, front-loading the critical warning about replacement semantics. Each sentence adds essential value, and there is no redundancy or 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 an update tool with replace semantics, the description covers all key aspects: the replacement warning, the need to read first, the concurrent write protection, and the handling of omitted fields. It does not need to explain the return format (no output schema) and the sibling tools are clear enough. The description is complete for an agent to use 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% with descriptions for all parameters, but the description adds crucial semantics beyond the schema, particularly the replacement behavior for emails and phones and the 'full list' requirement. This clarifies usage of parameters in a way the schema alone does not.

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 'Change an existing contact' with a specific verb and resource, clearly distinguishing it from siblings like contacts_create and contacts_get. It also mentions the field-level replacement semantics, which differentiates it from a generic update.

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 instructs the agent to read the contact first via contacts_get and send back the full list of the field being edited, and warns against the merge pitfall. It also notes the re-read before writing, which guides safe concurrent usage. This is explicit when/how 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?

Annotations declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description clarifies that the draft is not sent, which is a key behavioral trait, and it complements the openWorldHint by implying side effects (draft creation). However, it does not elaborate on other potential side effects (e.g., threading behavior via thread_id) or what the draft persistence entails, leaving some uncertainty.

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 exactly two sentences, front-loading the core purpose and usage condition. There is no redundant or filler content; every word earns its place. It is ideal for an agent to parse quickly.

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 8 parameters (4 required) and no output schema, the description is minimal but adequate for the core action. It does not mention return behavior, error handling, or prerequisites beyond what the schema states. The openWorldHint suggests potential side effects that are not disclosed, so the description could be more thorough, but it covers the essential intent.

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 each parameter described, so the baseline is met. The description adds no parameter-specific guidance beyond what the schema already provides; it simply states the overall action. It does not explain relationships between parameters (e.g., how thread_id interacts with 'to' or 'subject'), but the schema descriptions are sufficient for basic use.

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 uses a specific verb-resource pair: 'Save a draft' and clearly states the non-sending behavior. It distinguishes itself from send_message by explicitly noting when to use it ('whenever the user has not explicitly asked for the message to go out'), which differentiates 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 provides an explicit when-to-use condition ('Use this whenever the user has not explicitly asked for the message to go out'), which is clear and actionable. It does not name alternative tools like send_message or reply, but the implication is strong enough for an agent to infer the correct selection.

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 adds genuine behavioral detail beyond annotations: line breaks are preserved, formatting is lost, content is converted from plain text, and the return value is a document id plus open link. This is exactly the nuance needed for a creation tool and goes well beyond what readOnlyHint/destructiveHint provide.

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 sentences, no filler, and the key distinction ('not a text file') is front-loaded. Every sentence earns its place, including the return-value note.

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 creation tool with no output schema, the description covers behavior, formatting constraints, and return value. Combined with a fully documented schema, an agent has everything needed 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 description coverage is 100%, so the schema already documents all four parameters. The description only loosely maps 'from plain text' to the content parameter and does not add new per-parameter meaning, 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 and resource ('Create a real Google Doc') and explicitly contrasts it with a text file, which distinguishes it from sibling tools like drive_upload. It also tells the agent what the tool returns, leaving no ambiguity about what the tool does.

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 a clear usage signal: use this when you need a real Google Doc from plain text, not when you want a plain text file. It does not name an alternative sibling tool explicitly, but the 'not a text file' exclusion plus the sibling list is enough for an agent to route 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 readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond annotations by specifying the listing order ('sub-folders first'), which an agent would not otherwise know.

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 carry the core behavior, the root handling, and the main sibling alternative. Every sentence earns its place, and the primary 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 simple non-destructive listing tool with fully documented parameterschers, the description is mostly complete. It could be slightly stronger by mentioning what the returned entries look like, but since no output schema is present and the tool name/title make the listing nature clear, the gap is minor.

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 account, folder_id, and max_results. The description's note about omitting folder_id for the root essentially restates the schema's default-to-root behavior, adding no new 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 names a specific verb ('List') and resource ('what is inside a folder'), and even states the traversal order ('sub-folders first'). It clearly distinguishes itself from drive_search by contrasting the use case, so an agent can tell this is the enumeration tool for a known folder.

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 guidance: omit folder_id for root, and use drive_search when you know what you are looking for but not where it lives. This directly tells the agent when to use this tool and when to prefer a sibling 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?

Annotations already mark the operation as read-only, idempotent, open-world, and non-destructive, but the description adds valuable behavioral context beyond those: Google format exports, binary-file refusal with a link, and truncation behavior. It explicitly says truncation is indicated in the output, which an agent needs to interpret the result correctly.

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 concise and front-loaded. The opening sentence names the operation immediately, and each subsequent sentence adds a distinct, necessary behavioral fact without repetition or padding. 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?

There is no output schema, but the description covers what the tool returns: text content, exported formats, refusal with a link for binaries, and truncation notice. Combined with annotations that cover safety and the schema that covers parameters, this is sufficiently complete for an agent to 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?

The input schema has 100% description coverage and already documents each parameter clearly, including file_id provenance, account aliasing, and max_chars bounds/default. The description adds no additional parameter-level meaning, so the baseline of 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: 'Read a file as text.' It further describes the exact transformation behavior for different file types (Google Docs to plain text, Sheets to CSV, Slides to plain text), which clearly distinguishes it from sibling tools like drive_search, drive_list, drive_upload, and drive_create_doc.

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 conveys when it is appropriate to use this tool: when the agent needs the textual content of a file. It also gives a when-not signal by saying binary files are refused and not downloaded. However, it does not explicitly name alternative sibling tools or provide a direct comparison, so it stops short of full 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?

The description discloses parallel account search, merged result ordering, and partial failure semantics — behavior not captured in the annotations. This goes well beyond the readOnlyHint and idempotentHint annotations by explaining what happens when one account fails.

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: purpose, default behavior, failure handling, and parameter selection guidance are packed into a compact, front-loaded description. No fluff or repetition of schema fields.

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 still covers the key return behavior (merged list, ordering, failure reporting) and explains all important parameter interactions. An agent has enough information to call the tool correctly without guessing.

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 schema coverage is 100%, the description adds crucial meaning: 'query' matches filename and contents, 'drive_query' uses raw syntax and is ANDed with 'query', and 'max_results' is per account when searching all. These details are not inferable 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?

The description opens with 'Find files in Google Drive', a specific verb and resource, then immediately explains the multi-account search behavior that sets it apart from sibling tools like drive_list or drive_read. The distinction between plain query and raw drive_query further clarifies the tool's 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 clear conditional guidance: omit 'account' to search all connected drives, use 'query' for plain words, and use 'drive_query' only when raw Drive syntax is required. It does not explicitly compare against sibling search tools like search_emails, but the usage context within this tool 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?

Beyond the annotations (destructiveHint, readOnlyHint false), the description adds essential behavioral warnings: 'GIVES AWAY ACCESS to real data and cannot be undone from here', 'anyone ... readable by ANYONE WITH THE LINK', and the notification email default. This significantly exceeds what the schema and 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?

Every sentence contributes meaningful guidance, with the most critical warning front-loaded ('cannot be undone from here'). Despite covering several parameter nuances, the description remains tight and scannable.

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 eight parameters and no output schema, the description covers the highest-risk decision points (permission type, irrevocability, notify behavior). Remaining parameters like account, file_id, role, and message are adequately documented in the schema, so little 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 coverage is 100%, so the baseline is 3. The description adds valuable parameter-level context: it explains the 'type' conditional requirements, the public-link implication of 'anyone', and the notify default. This goes beyond the schema's own descriptions.

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

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

The description clearly states the action ('Grant someone access to a file') and is distinct from sibling tools like drive_search, drive_read, or drive_upload. The resource and verb are specific, and the title reinforces the action without being a mere tautology.

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 concrete usage guidance for permission types, including when to use 'anyone' ('only use it when the user asked for a public link in so many words') and conditional requirements for user/group versus domain. It doesn't explicitly name alternative tools, but the sharing action is clear enough that no alternative appears likely.

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 useful behavior beyond the readOnly/idempotent annotations: omitting account queries every configured account, and the returned canAddChildren field indicates write permission. It also clarifies that shared drives cannot be discovered through drive_search.

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 sentences, front-loaded with the core purpose, and every sentence earns its place. The NOT-a-file clarification, id-resolution role, and account-scoping/output-field note are all necessary and free of 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 read-only list tool with no output schema, the description still explains the returned ids and canAddChildren field, account selection behavior, and relationship to sibling tools. The main completeness gap is the unresolved conflict between the description and the required account parameter.

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's claim that omitting account asks every configured account directly contradicts the schema's required: ['account']. This is misleading rather than purely additive. The max_results parameter is left to the schema, which is acceptable.

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 action and object: list shared drives and return their ids. It also distinguishes itself from drive_search by clarifying shared drives are not files and never appear in search results, making its 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?

Clearly explains when to use it: when you need to convert a shared drive name into an id for drive_list, drive_upload, or drive_share. It gives a concrete decision rule by noting that drive_search cannot find shared drives, and it explains account-scoping behavior.

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 and destructiveHint=false, so the write nature is known. The description adds a useful privacy note ('The file is private to the account until something shares it'), which goes beyond annotations. It does not describe overwrite behavior, return format, or side effects like idempotency, but the annotations cover the basic safety profile.

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 sentences with zero filler. The action is front-loaded, and the exclusivity constraint and privacy note are delivered efficiently. 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?

For a 6-parameter tool with no output schema, the description covers the main decision (content vs. path) and the default folder behavior is in the schema. However, it does not mention what the tool returns (e.g., file ID or URL), which is important for chaining operations. It also omits any mention of authentication requirements or failure modes, leaving some 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 each parameter has a description. The tool description adds critical meaning by specifying that content and local_path are mutually exclusive ('exactly one of the two'), a constraint not present in the schema. This clarifies a non-obvious relationship and aids correct invocation.

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 clear verb+resource ('Put a file in Drive') and immediately distinguishes two input modes (inline content vs. local file). It is specific enough to separate this from sibling tools like drive_create_doc or drive_read, and the title reinforces the action.

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 guidance on when to use content versus local_path ('exactly one of the two'), which is valuable. However, it does not explicitly contrast this tool with alternatives (e.g., drive_create_doc for Google Docs) or state when not to use it. The usage context is implied but not explicit about 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 establish that this is a non-read-only, idempotent, non-destructive mutation. The description adds real behavioral detail beyond the annotations: label names are matched case-insensitively, either names or IDs are accepted, and removing UNREAD has the side effect of marking the message read. This meaningfully improves the agent's understanding of 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?

Four short sentences, each carrying distinct information: the action, label identifier flexibility, useful system labels, and the UNREAD-to-read side effect. There is no redundancy or filler, and 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 with four parameterscraper, the description plus schema covers the required fields, label value formats, and important side-effect semantics. It does not explicitly warn that calling it with neither add_labels nor remove_labels is a no-op, nor describe the response shape, but these are minor gaps given the idempotentHint and the absence of 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?

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining that add_labels and remove_labels accept both label names and IDs, that names resolve case-insensitively, and that the UNREAD label has special read-marking semantics. This helps the agent construct correct label values beyond just reading 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 and resource ('Apply and/or remove labels on a message') and clearly distinguishes this from sibling tools like list_labels and trash_email by focusing on label mutation. It also clarifies the label namespace and case-insensitive name resolution, leaving no doubt what operation is performed.

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 when to use it—when a message's labels need changing—and lists useful system labels, which gives practical context. However, it never explicitly contrasts this with list_labels, trash_email, or untrash_email, nor does it state conditions when an alternative should be preferred. The guidance is adequate but not 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 cover the safety profile (readOnlyHint, openWorldHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuine behavioral context beyond that: accounts may exist yet be unusable, and this tool reports that state. It is consistent with annotations — listing is read-only and idempotent.

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?

Exactly two sentences: the first delivers the core purpose, the second front-loads the usage trigger. No filler, no repetition of schema or annotation content, 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?

For a simple tool (one optional param, no required params, no output schema) with annotations covering safety, the description covers purpose and usage triggers well. The only minor gap is that the return format is not described and there is no output schema to fill it, but the shape of a discovery list is largely predictable.

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%: the single "probe" parameter is fully documented in the schema (boolean, contacts Gmail, slower, detects revoked tokens, defaults false). The description only hints at this via "whether it is usable," so the schema does the heavy lifting — 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?

"List every configured Gmail account and whether it is usable" names a specific verb (list), resource (configured Gmail accounts), and added scope (usability status). It is unambiguous against the sibling list_labels — that tool lists labels, not accounts — so an agent can tell them apart 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?

"Call this first when you do not know which accounts exist, or when another tool reports an unknown account" gives explicit, actionable trigger conditions. For a discovery tool with no genuine sibling alternative, the absence of a when-not clause is not a real gap.

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, and non-destructive behavior, so the description does not need to repeat them. It adds context about what categories of labels are returned and how results relate to label_message. It does not describe pagination or exact response shape, but those are minor for a simple label 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?

Two sentences, with the primary action and scope in the first and usage guidance in the second. No filler, no repetition of schema content, and the information is effectively 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 one-parameter read-only listing with rich annotations, the description gives the required scope, the output contents (labels and ids), and when to call it relative to label_message. The absence of an output schema is compensated by explicitly stating that ids are included.

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 single account parameter already described as an email address or alias. The description only restates the account scoping ('of an account') and adds no new syntactic or format guidance. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('List'), the resource ('labels of an account'), and the useful detail that both system and user-created labels are included with ids. The mention of 'Call this before label_message' also distinguishes it from the only sibling that operates on labels.

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 when to call: before label_message when unsure a label exists. It points at the alternative label_message by name, giving clear routing guidance. It doesn't enumerate other alternatives, but none are needed for a pure list operation.

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 read-only and idempotent behavior, and the description adds the valuable caveat that attachment contents are not downloaded. This goes beyond the structured metadata by clarifying the scope of the result.

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 two sentences with no filler. The primary purpose is front-loaded and the crucial limitation about attachments is stated immediately after the core behavior.

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, read-only tool with fully described parameters and safety annotations, the description covers the important behavior and limits. It could mention what is returned in more detail, but the absence of an output schema is mitigated by describing the body and attachment metadata.

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 input schema already provides full descriptions for both parameters (100% coverage). The tool description adds no parameter-specific detail, so the baseline of 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?

The description uses a specific verb and resource ('Read one message in full') and explicitly states the scope of the result (decoded body and attachment metadata). This makes the tool easy to distinguish from siblings like search_emails and read_thread.

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?

No explicit guidance is given about when to use this tool versus alternatives like read_thread or how it fits into a workflow after search_emails. The description implies its use but does not state when not to use it or name any companion tools.

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 establish readOnly, openWorld, idempotent, and non-destructive behavior, so the description's added value is in stating that the tool returns the complete thread ordered as a full conversation. It also communicates that the output provides exchange-level context rather than an isolated message, which goes beyond the annotations. It does not describe the response fields or pagination, but no annotation contradiction exists.

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 two tightly written sentences with no filler. The first sentence states the core behavior and scope, and the second sentence adds the comparative usage guidance. Every word contributes to tool selection or invocation.

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 tool has only two required parameters and a full schema, the description covers the main behavior and expected output order. The only gap is the lack of detail about the exact structure of returned messages, such as headers or bodies, but the absence of an output schema and the simple read-only nature keep this close to complete.

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 input schema has 100% description coverage, documenting both required parameters: thread_id is described as returned by search_emailseding an email address or alias for account. The description adds no additional parameter-level details, so the baseline score of 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?

The description uses a specific verb, 'Read', and a clear resource, 'a full conversation,' and states that it returns 'every message in order.' It explicitly contrasts with read_message by targeting the context of an exchange rather than a single email, making the tool's purpose unambiguous and distinguishing it from 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?

The description gives direct selection guidance: 'Prefer this over read_message when you need the context of an exchange rather than a single email.' This names the alternative tool and the condition that should trigger the choice, so an agent knows when to use this tool versus read_message.

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 indicate non-readonly, non-idempotent, and non-destructive behavior. The description adds valuable context beyond that: it handles subject prefixes and In-Reply-To/References headersWorld, and it emphasizes that the action sends immediately. This is critical behavioral information for an agent deciding whether to invoke a side-effecting 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?

Three short sentences deliver the essential message efficiently: what the tool does, why it behaves as a reply, and that it sends immediately. Every sentence earns its place, and the immediate-send warning is front-loaded at the end for emphasis without being wordy.

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 5-parameter send action with no output schema, the description covers the key behavioral risks and thread semantics. It does not mention return values, errors, or delivery guarantees, but the schema fully documents parameters and the tool is simple enough that those omissions are minor.

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 every parameter clearly. The description adds no parameter-level meaning beyond the schema, such as how body, is_html, or reply_all interact. A baseline score of 3 is appropriate because the schema carries the full semantic weight.

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: 'Send a reply that stays in the original thread.' It clearly distinguishes the tool from sending a new message by emphasizing thread continuity and header handling. It also differentiates from draft creation with the explicit warning 'This SENDS immediately.'

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 when to use the tool: when the intent is to reply within an existing thread rather than start a new conversation. It also signals that the tool sends immediately, contrasting with a draft workflow. However, it never explicitly names alternatives like send_message or create_draft, nor states when not to use it.

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 read-only, idempotent, non-destructive behavior. The description adds meaningful behavioral context beyond that: parallel search across accounts, a merged and date-sorted result, partial failure tolerance, and an explicit 'failures' field. This substantially helps an agent anticipate what happens at runtime.

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 sentences with no filler. The query syntax example is front-loaded, followed by the key scoping behavior and then failure semantics. Every sentence contributes essential 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 simple 3-parameter search tool, the description plus annotation set covers defining query syntax, account scoping, result ordering, and partial failure behavior. It does not detail the shape of the returned message objects, but the absence of an output schema is partially mitigated by the clear description of the merged date-sorted list and failures field.

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 value by showing a concrete Gmail query example and emphasizing that omitting 'account' triggers a parallel search across all mailboxes. The max_results parameter is left to the schema, which documents it clearly.

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 ('search') and resource ('emails') and adds the essential Gmail query syntax. It clearly distinguishes this from sibling retrieval tools like read_message by framing it as query-based search, and the cross-mailbox behavior further pins down what the tool does.

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 operational guidance: omit 'account' to search all mailboxes, or include it to restrict the search. It describes a concrete invocation strategy and failure behavior. It does not explicitly name alternatives or exclusion criteria, but none of the sibling tools perform the same email search role.

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 behavioral context beyond the annotations: the send is immediate and irreversible ('There is no undo'). This is a critical warning for a mutating side-effectful action. While it doesn't discuss failures or delivery semantics, the core risk is clearly disclosed.

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 action and immediacy are front-loaded, the no-undo warning is prominent, and the alternative tool is named concisely. No filler or redundant phrasing.

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 8-parameter mutating tool with no output schema, the description provides the necessary side-effect warning, user-intent safeguards, and routing guidance. Combined with the fully documented input schema, an agent has enough 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?

The input schema already documents all 8 properties with meaningful descriptions, so the tool description adds little parameter-specific detail. Baseline 3 is appropriate because the schema carries the explanatory burden fully.

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?

Uses a specific verb and resource ('Compose and SEND a new email immediately') and clearly differentiates from create_draft by stating that sending happens now. The title and description align, and a sibling tool shares the email domain 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?

Explicitly directs the agent to use create_draft when the user has not clearly asked for the message to be sent. This is a concrete conditional routing rule, which is ideal guidance for choosing between two otherwise similar sibling tools.

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 provide readOnlyHint=false and destructiveHint=true, but the description adds significant behavior beyond that: it is not permanent, the message stays existing, untrash_email can restore it, Gmail auto-empties after 30 days, and a wrong ID is visible in the response. This gives the agent a much richer model of the tool's 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 front-loaded with the core action and then adds only high-value caveats: reversibility, the 30-day limit, absence of permanent delete, and response feedback. No sentence is wasted, and the structure is easy to scan.

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 two-parameter tool with no output schema, the description covers everything needed: what the tool does, its side effects, how to undo it, and what to look for in the response. It also addresses the relevant sibling untrash_email and the lack of a permanent-delete alternative.

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 ('Configured account' and 'Message to move to the bin'). The description adds little beyond naming the bin, so the baseline of 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?

The description opens with a specific action and resource: 'Move a message to the bin.' It distinguishes this from a permanent delete and from recovery via untrash_email, so an agent can immediately tell what the tool is for and how it differs from related actions.

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 usage context clear by explaining that this is reversible for 30 days and that no permanent-delete tool exists. It doesn't literally say 'use this when you want to soft-delete and use untrash_email to undo,' but that is strongly implied by the contrast with untrash_email and the warning about Gmail's 30-day emptying.

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 adds behavioral context beyond the annotations: it restores prior labels and has a 30-day recovery window. It does not describe failure modes or authorization requirements, but the annotations already signal mutation and idempotency, and nothing contradicts the structured metadata.

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 deliver purpose, limitation, and the discovery alternative in order. Every sentence earns its place and the most important 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?

For a two-parameter recovery tool, this description is nearly complete: what it does, when it works, and how to find eligible messages are all present. The only missing piece is the response format, but with no output schema and a side-effect-driven operation, this 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 both account and message_id have meaningful schema descriptions. The tool description does not add extra format or syntax guidance for the parameters, so the baseline of 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?

Description opens with a concrete action, 'Take a message back out of the bin and restore the labels it had,' specifying both the resource (trashed email) and the expected effect. This clearly distinguishes untrash_email from trash_email and search_emails.

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?

States a hard precondition: only works while the message is still in the bin, with a 30-day Gmail expiration limit. It also explicitly directs the agent to search_emails with 'in:trash' to find recoverable messages, giving a clear when-to-use and when-to-look-elsewhere guideline.

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