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

Annotations already mark this as a non-read-only, non-idempotent, non-destructive write. The description adds useful behavioral context beyond that: the server generates UID and file name, and the vCard version is resolved based on the address book. 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?

Two concise, front-loaded sentences with no filler. The first states the purpose; the second adds meaningful behavioral detail about UID generation and vCard version. Each 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?

The output schema and annotations carry some burden, but this is a 22-parameter tool with low schema coverage. The description covers the basic create flow but leaves out important contextual choices such as structured fields versus raw_vcard and how this differs from updating an existing contact. It is adequate for a simple call but not complete for sophisticated use.

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?

With only 27% schema description coverage across 22 parameters, the description needed to compensate, but it only clarifies that UID/file name are server-generated and mentions vCard version behavior. It does not explain how the many structured fields map to vCard, when to use raw_vcard, or how the address book parameter should be sourced.

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: 'Adds a card to an address book.' It also adds distinguishing detail by noting that the UID and file name are generated here, which separates creation from updating an existing 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?

The description gives no guidance on when to use this tool versus alternatives like update_contact, delete_contact, or import/export tools. It implies creation but does not state exclusions or direct the agent to a sibling for existing contacts.

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 an important getcha: the group must follow the address book's exsting convention or it becomes invisible to the user. This is meaningful behavioral context that annotations do not carry. 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?

Two tight sentences with no filler. The primary action is front-loaded, and the critical convention caveat is delivered in the second sentence without extrta 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?

The description covers the tool's purpose and the essential behavioral constraint, and an output schema exists so return values need not be describeed. It lacks alternative routing and some edge-case behavior, but it is otherwise adequate for calling 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?

With four parameters and only 75% schema coverage, the description adds little parameter meaning. The phrase 'named contacts' is vague and could misleader an agent into think contacts are names rather than IDs. It does not clarify address_book or note semantics beyond what the schema already states.

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

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

The description states a specific action ('Creates a group card') and a clear resource, and sets it apart from sibling tools like create_contact and update_group. The title reinforces the resource, making it unambiguous what this 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?

No when-to-use guidance is offerered. It does not mention when to choose create_group over update_group or create_contact, and it does not state any prerequisites or exclusions. The convention note is behavioral, not usage routing.

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, which already mark this as destructive and idempotent, the description adds valuable behavior: deletion cannot be undone because CardDAV has no trash or version history, and it is ETag-guarded so a stale delete is refused. This meaningfully informs an agent about consequences and safety mechanisms.

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 short sentences with no filler. It front-loads the core action, immediately states the permanence consequence, and then explains the safety guard. Every sentence adds distinct information.

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

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

For a two-parameter deletion tool with a full output schema and explicit annotations, this description is complete. It covers what the tool does, why it is dangerous, how stale deletes are prevented, and the role of confirm_token via the schema. No critical call-time information 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%, and both id and confirm_token are already well-documented in the input schema. The description adds contextual behavior around ETag guarding and refusals but does not describe the parameters themselves, so it stays 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 'Removes a card,' a specific verb and resource that clearly identifies the operation as deleting a contact card. This is unambiguous and distinguishes it from sibling update/delete tools targeting other entities like 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 implies usage by stating it removes a card and emphasizing that deletion is permanent, which signals when to use it. However, it does not explicitly discuss when not to use it or compare it against alternatives such as update_contact or delete_group, though the tool name and resource type make the primary use case obvious.

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

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

Annotations already mark this as destructive and non-read-only. The description adds important behavioral detail beyond annotations: it is irreversible ('Cannot be undone') and it does not delete the underlying contacts. This clarifies side effects that an agent needs to know before calling.

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

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

Three short sentences, each carrying essential information: what is removed, what is preserved, and that the action is irreversible. No filler, no redundant restating of the title or schema.

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

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

With an output schema and annotation hints present, the description covers the core semantics and critical side effects. The confirm_token flow is only in the schema, but that is acceptable since the schema documents it fully. The definition is largely 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?

Schema description coverage is 100%, with both parameters (id and confirm_token) already explained in the input schema. The tool description adds no parameter-specific meaning, so it correctly stays at the baseline where the schema carries the 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 states a specific verb and resource: 'Removes a group card.' It also distinguishes itself from contact deletion by clarifying 'The contacts that were in it are not touched — only the grouping goes.' This makes the tool's purpose unmistakable even among sibling tools like delete_contact and list_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 gives useful context: this tool removes the grouping but not the contacts. However, it does not explicitly name alternatives or state when-not-to-use conditions, such as 'To delete the contacts themselves, use delete_contact.' The usage guidance is implied rather than 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 read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond that: it returns data exactly as stored and exposes unmodeled properties, which clarifies behavioral expectations for an agent comparing against the modeled get_contact tool.

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, no wasted words. The main return value is front-loaded, and the second sentence justifies the tool's unique value without 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?

Given the rich input schema, output schema, and annotations, the description is complete. It explains the raw format, exactness, and unique use cases, while the schema covers parameter semantics and the output schema covers return structure.

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?

Input schema coverage is 100%, so all three parameters are already documented with descriptions. The tool description does not add parameter-level detail, but it does not need to since the schema 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 states a specific outcome: raw vCard text of one or more contacts, exactly as stored. It also differentiates itself from siblings by noting it is the only way to see properties the server does not model and the only way to back up an address book.

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 signals when to use this tool: when raw vCard fidelity is needed, when unmodeled properties must be accessed, or when taking a backup. It does not explicitly name alternatives or state when not to use it, but the 'only way' framing gives strong contextual 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 already cover read-only, idempotent, non-destructive behavior, so the description adds value by disclosing output traits: unmodelled properties are surfaced by name, and free text is fenced so it is not mistaken for server-generated prose. 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?

Two sentences, immediately front-loaded with the core purpose ("complete card behind an id"), and every phrase carries information. The list of fields and the fencing detail add value without padding.

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-paramter read with rich annotations and an output schema, the description is complete: it specifies the input source, the full scope of the return, and the presentation of free text. No critical calling information appears to be 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?

The only parameter is id, and its schema description already explains valid origins (list_contacts, search_contacts, etc.) at 100% coverage. The tool description adds no new parameter semantics beyond referring to "an id", so the baseline 3 applies.

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

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

The description states a specific verb and resource ("Read one contact in full") and explains what "full" means: every address, phone number, note, birthday, and names of unmodeled properties. It distinguishes itself from list_contacts and get_contact_photo by emphasizing the complete card rather than a summary or a single artifact.

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 and schema clearly indicate the entry point: an id produced by list_contacts, search_contacts, list_groups, or list_changes. This tells an agent when it can call this tool, though it does not explicitly say when to prefer a sibling like get_contact_photo or search_contacts.

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 meaningful behavioral context by explaining that linked photos are never fetched because the address was chosen by the card writer, and that only embedded photos are returned. It does not cover edge cases like missing photos, but the annotations lower the burden.

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 no filler. The main return behavior is front-loaded, and the caveat about linked photos follows naturally. 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 one-parameter read-only tool with an output schema, the description covers selection, invocation context, and the key boundary case. It could more explicitly state what happens when no embedded photo exists, but the annotations and schema fill most of the remaining context.

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 sole id parameter has 100% schema coverage and a clear description listing its source tools. The tool description does not add extra parameter-level meaning beyond that, so the schema carries the weight and 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 states a specific verb and resource: it returns the photo stored on a card as an image. It also distinguishes itself from get_contact by clarifying that linked photos are reported by get_contact and never fetched, so an agent can tell the two tools apart.

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 names get_contact as the alternative and gives a clear condition: use this tool for photos embedded in the card itself, and get_contact for photos stored as links. This explicitly tells the agent when to use the tool and when not to.

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 meaningful behavioral detail beyond the annotations: member resolution to names/ids when in the same address book, and the fallback behavior of reporting unresolvable members as references. This goes beyond what readOnlyHint/idempotentHint already communicate.

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, front-loads what the tool returns, and adds only valuable resolution details. No redundant or filler wording is present.

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-one-group operation with complete schema coverage, an output schema, and annotations covering safety and idempotency, the description is fully sufficient. It even clarifies an edge case about unresolvable member references.

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 fully describes the single `id` parameter with sources like list_contacts, search_contacts, list_groups, or list_changes. The description adds no additional parameter-specific meaning, but with 100% schema coverage the 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?

The title states a specific verb and resource: 'Read one group, with its members'. The description elaborates precisely on what is returned—a group card and its contacts—making the tool's purpose unambiguous and distinct from siblings like get_contact or list_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 this tool is for retrieving a single group along with its member contacts. It does not explicitly name alternatives or exclusions, but the context makes it obvious when to use this tool versus list_groups or get_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?

Annotations already declare this as read-only, idempotent, and non-destructive. The description adds useful behavioral context beyond those hints: it performs live capability probing (checking whether optional features actually work) and warns that CardDAV implementations vary. 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?

Two tightly written sentences. The first front-loads the concrete output substance; the second adds a pragmatic trigger for when to call the tool. Every clause earns its place; no filler or schema 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?

With no parameters, an output schema present, and annotations covering the safety profile, the description fully covers what an agent needs: what it reports, why it matters, and when to run it. Nothing material 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?

The tool has zero parameters, so the description is not required to explain parameter meaning. The baseline of 4 applies, and the description appropriately focuses on what the returned information will tell the agent rather than on inputs.

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 ('Reports') and identifies a distinct resource: the connected CardDAV server's capabilities, including DAV compliance tokens and supported vCard versions. This clearly distinguishes it from sibling tools that operate on contacts, address books, or 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?

Explicitly states when to use it: 'The first thing to run when something behaves differently than expected.' This gives clear contextual guidance, though it doesn't name specific alternative tools or exclusion cases, so it falls just short of a 5.

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

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

Beyond the annotations, the description adds a meaningful behavioral trait: 'Always asks the server rather than answering from a cache — being current is this tool’s whole job.' This informs the agent that freshness is guaranteed and that caching should not be assumed. 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?

Two sentences, both purposeful. The first sentence front-loads the core outcome (list of address books with IDs), and the second adds the non-obvious freshness behavior. No wasted words.

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

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

For a zero-parameter, read-only listing tool with an output schema present, the description fully covers what the tool does, how the results connect to other tools, and its key behavioral guarantee. Nothing essential 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?

The tool has zero parameters and the schema coverage is 100%, so there is no parameter detail to clarify. Per the 0-params baseline, the description is not required to add parameter semantics and does not need to compensate for any gap.

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: 'Every address book this server may use, with the id to pass to the other tools.' This clearly differentiates the tool from sibling list tools like list_contacts and list_groups by focusing on address books and their IDs.

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 for when to use this tool: to obtain the list of available address books and the IDs needed by other tools. It does not explicitly name alternatives or exclusions, but the resource-specific purpose and mention of downstream use make the intended usage apparent.

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 explains the sync-token protocol, the initial-sync behavior, and the server-support caveat. It also names the underlying standard (RFC 6578), giving the agent a clear model of what the call does and what could go wrong.

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-ordered sentences convey the core behavior, the call sequence, and an important limitation with no filler. The most important information is front-loaded in the first clause.

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 sync operation, the description covers the essential protocol, the initial vs. subsequent call, and the prerequisite capability check. The presence of an output schema means return values need not be described, and the input schema covers parameters.

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 meaningful semantics for sync_token: leaving it out returns the current token and every card as the initial sync. This enriches the bare parameter description with the exact call pattern. It does not add much for limit or address_book, but that is acceptable given the schema already documents them.

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 identifies the operation: returning cards created, changed, or deleted since a sync token. This is specific enough to distinguish list_changes from siblings like list_contacts or search_contacts, which return current card data rather than a change set.

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 procedural guidance: call once without a token to get the current token, then call again later with it. It also warns that not every server implements RFC 6578 and routes the agent to get_server_info for capability detection, which is valuable decision support.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful context beyond annotations: it discloses that only summary properties are fetched (not full cards), that group cards are excluded by default and why, and that the operation is cheap. This exceeds what annotations 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 sentences, front-loaded with the core behavior and outcome, then a cost/routing clarification. Every clause earns its place: the summary format, the cheapness rationale, and the pointer to get_contact are all necessary for correct tool selection.

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 is complete for a read-only, idempotent listing tool with a rich schema and an output schema present. It explains the return style (short summaries vs full cards), the group exclusion default, the cost trade-off, and how to get the alternative behaviors via sibling tools. 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 fully documents limit, address_books, and include_groups. The description adds context about why include_groups defaults to off and connects address_books to list_address_books outputs, but this is modest enrichment over a fully-covered schema. 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?

The description states a specific verb ('list') and resource ('contacts in one or more address books'), and immediately specifies what form the listing takes ('short summaries: name, organisation, addresses and phone numbers, and whether a photo is present'). This clearly distinguishes list_contacts from get_contact, which returns the whole card.

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 get_contact and list_groups as alternatives and explains when to use them instead: get_contact for a full card, list_groups for proper group card reading. It also states the cost-saving rationale ('only the summary properties are fetched, so this stays cheap'). This is strong usage 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 already declare the tool read-only, idempotent, and non-destructive. The description adds valuable behavioral detail beyond that: it returns member counts, does not resolve members, and warns that resolving members would require an extra request per address book. This gives the agent useful expectations about cost and output scope.

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, no filler. The core behavior is stated first, and the important distinction from get_group is included without redundant detail. Everything 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?

The description is complete for a read-only listing tool: it explains the return scope, the member-count behavior, and the path to get member names. The presence of an output schema reduces the need to describe return values. A minor gap is not stating what happens when address_books is omitted, but the schema already covers that.

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 both parameters fully at 100% coverage, including defaults, constraints, and the meaning of omitting address_books. The description reinforces the address book concept and the absence of member resolution but does not need to add more because the schema carries the 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 clearly states that this tool returns groups in one or more address books along with member counts, establishing a specific verb and resource. It also differentiates itself from get_group by explicitly stating that member names are not resolved here.

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 for when to use this tool versus get_group: use this for group listings and member counts, and use get_group when the caller wants member names. It does not enumerate all sibling alternatives, but the key distinction is explicit and actionable.

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 annotations by revealing the non-transactional nature: 'the copy is verified before the original is removed.' It also explains the id change, which is a surprising side effect. This is valuable behavioral context beyond the destructiveHint 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 concise sentences with no wasted words. The first sentence states the core action, the second explains a key side effect, and the third warns about the non-transactional behavior. Information is front-loaded and each sentence adds value.

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 that the output schema exists and annotations mark the operation as destructive, the description covers the essential behavioral quirks: non-atomcity and id change. It does not explicitly state prerequisites or alternatives, but the schema and annotations carry most of the remaining burden, making the description appropriately 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?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds context about the id changing, which helps explain id semantics, but it does not clarify destination or confirm_token further. This meets the baseline for high schema coverage without adding much parameter-specific detail.

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

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

The description clearly states the action: 'Copies a card into another address book and removes it from the first.' This distinguishes it from delete_contact, create_contact, and update_contact. The note about id changes reinforces the move semantics.

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 title and description make the use case obvious, but no explicit guidance is given about when to use this tool versus alternatives like delete_contact or create_contact. The description does not mention exclusions or alternative tools; it relies on the word 'move' to imply the scenario.

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?

Even with readOnlyHint, idempotentHint, and destructiveHint already set, the description adds valuable behavioral disclosure: it reveals one request is made per address book, fields are combined with OR in CardDAV, and results are re-checked because some servers only partially filter. This is exactly the kind of non-obvious runtime behavior an agent needs to anticipate.

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 wasted words. The primary purpose is front-loaded, and the second sentence delivers the most important behavioral caveat. The parenthetical CalDAV contrast is brief and earns its place by highlighting a protocol-specific difference.

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 full input schema, a present output schema, and annotations covering safety and idempotency, the description supplies the remaining non-obvious context: partial server filtering and per-address-book request behavior. An agent has enough information 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?

The schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaningful parameter behavior beyond the schema by explaining that fields are combined with OR and that requests are issued per address book, which clarifies how the fields and address_books parameters actually behave.

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 ('Finds contacts') and precisely scopes the resource by listing the searchable fields: name, organisation, email address, phone number and note. This clearly differentiates it from sibling tools like list_contacts or get_contact, which do not perform term-based search across multiple fields.

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 intended use is implied by the search semantics, but the description never explicitly says 'use this when you need term search' or contrasts it with list_contacts/export_contacts for retrieving all contacts. The CardDAV versus CalDAV note provides protocol context but not actionable when-to-use versus when-not-to-use 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?

The description goes well beyond the annotations by disclosing merge semantics, preservation of unmodeled properties, ETag-based refusal of concurrent changes, lack of version history, and human confirmation. It slightly overstates preservation because the raw_vcard parameter replaces rather than merges, so it does not quite earn a 5.

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

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

Three sentences, each earning its place: core merge behavior, concurrency guard, and irreversibility/confirmation. The most important semantic is front-loaded before secondary details.

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 23-parameter mutation tool, the description is unusually complete: it covers semantics, concurrency, and consequences. It omits the raw_vcard exception and the confirm_token workaround, but these are documented in the schema, so the description remains largely sufficient.

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?

With only 30% schema description coverage, the description needs to compensate, and it does add one global rule: unspecified fields are left untouched. However, it does not explain individual parameter purposes, the special behavior of raw_vcard, or how confirm_token relates to the confirmation flow; the schema carries most field-level burden.

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

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

The description states a specific verb ('Changes') and a specific resource ('the fields named' on a contact), and the title confirms the contact scope. It clearly differentiates from sibling tools such as create_contact, delete_contact, and get_contact by describing partial-update semantics.

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 intended use—modifying an existing contact's fields—is clear from the title and behavior, but the description gives no explicit when-to-use guidance or comparison with alternatives like create_contact, delete_contact, or raw_vcard replacement. There are no exclusions or conditions such as 'use raw_vcard when replacing the whole card'.

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 destructiveHint=true, but the description adds crucial context: removing a member only affects the grouping, not the contact, and no version history means a person is asked first. This explains the confirmation flow and non-destruction of underlying contacts beyond the structured 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 sentences with no filler. The first sentence states the core function, the second clarifies a critical non-destructive nuance, and the third explains the confirmation reason. Everything earned 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?

The description combines with the schema's confirm_token and set_members descriptions and the output schema to give a reasonably complete picture. It could add explicit guidance on how add_members/remove_members/set_members interact, but the schema already covers the crucial constraint on set_members.

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

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

Schema coverage is only 43%, so the description must compensate. It clarifies the roles of name/note and add/remove_members, but it doesn't explain set_members as a wholesale membership replacement nor the confirm_token mechanism directly. The schema does cover set_members and confirm_token, but the description only partially bridges the gap for the remaining parameters.

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 uses a specific verb ('Changes') and names the exact resources affected: group name, note, and membership. It clearly differentiates the tool from sibling create_group/delete_group/get_group by describing what it modifies on an existing 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?

Description makes the usage context clear: use it to update a group's name/note or add/remove members. It doesn't explicitly name alternatives or when-not-to-use, but the wording strongly implies modification of existing groups and distinguishes itself from deleting contacts or creating groups.

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