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

Adds substantial context beyond the annotations: the first invocation is a no-write preview, the write only occurs on the confirmed second call, and the token is bound to identical arguments. This is consistent with readOnlyHint=false and destructiveHint=false, and discloses the two-phase write semantics an agent could not infer otherwise.

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 purpose and then the critical two-step protocol. No filler; every clause is actionable.

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

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

With no output schema, the description still explains what the first call returns (a preview and confirm_token) and what is required to commit the write. Nothing essential to correct invocation is missing.

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

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

Schema description coverage is only 20%, so the description must carry the load. It explains deal_id's optional linkage and the confirm_token flow, but adds nothing about due's date format or note's length/format constraints, which remain schema-only.

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 ('Schedule a follow-up reminder for a contact') plus the optional deal association. It is clearly distinguishable from siblings like complete_follow_up, list_follow_ups, and draft_outreach.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit operational guidance: the first call must omit confirm_token, the user must approve the preview, and the second call must repeat identical arguments plus the token. It does not name alternative tools for related cases (e.g., when to complete vs. add), so it stops 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 (readOnlyHint=false, idempotentHint=true, destructiveHint=false), the description discloses the critical two-step behavior: the first call writes nothing and only returns a preview plus token. This is exactly the kind of non-obvious side-effect behavior an agent must know, and it is stated explicitly.

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, zero filler, and the confirm-token protocol is front-loaded with the key constraint ('nothing is written') emphasized. Every clause carries actionable information.

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

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

With no output schema, the description still describes what the first call returns (a preview and a confirm_token) and what the second call does, which is the essential return/confirm information for this workflow. Nothing needed to invoke it correctly is missing.

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

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

confirm_token already carries a schema description, and the tool description reinforces its role ('no confirm_token' yields a preview; pass the token with identical arguments to apply). follow_up_id is left to its pattern/name, but its meaning is self-evident for this resource.

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

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

The opening sentence states a specific verb and resource ('Mark a follow-up as done'), which cleanly separates it from siblings like add_follow_up, list_follow_ups, and log_activity. An agent knows exactly what state change this tool produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use guidance and a precise call sequence: first call without confirm_token to preview, then call again with identical arguments plus the token after user approval. It does not name alternative tools for adjacent tasks, but the operational protocol 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?

Annotations declare destructiveHint=true and idempotentHint=true, but the description adds the crucial detail that the first call is non-writing (a dry-run preview) and that deletion cascades to related deals, follow-ups and activities. That cascade and the two-phase safety mechanism are not derivable from the annotations or schema.

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, front-loaded with the destructive cascade, then the two-step mechanics. No filler, no repetition of the title, and the riskiest fact comes first.

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 mutation with no output schema, the description covers the safety model, the write semantics, the cascade blast radius, and the return behavior of the preview call. An agent has everything needed to call it correctly and safely.

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

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

Schema coverage is only 50% (contact_id is undocumented in the schema), but the description compensates by explaining the confirm_token lifecycle: omitted on the first call, passed from the preview with identical arguments on the second. The pattern/format of contact_id itself remains undocumented.

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 ('Permanently delete') and resource ('a contact'), and immediately clarifies the cascade scope ('AND their deals, follow-ups and activities'). This distinguishes it cleanly from delete_deal and the other 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?

Gives an explicit two-step protocol: first call without confirm_token returns only a preview, the agent must show it to the user, and only after approval re-call with identical arguments plus the token. The when-to-call-each-form condition is spelled out with no inference required.

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 destructiveHint=true and idempotentHint=true, but the description adds materially new behavior: the delete is permanent, linked follow-ups are unlinked rather than removed, and the first invocation is a no-write preview. That confirmation-gate detail is not derivable from any annotation or schema field.

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

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

Two compact sentences, no filler. The permanence and cascade facts are front-loaded, and the two-step workflow follows immediately, so an agent reads the risky semantics before the mechanics.

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 mutation with no output schema, the description supplies the missing return-value context (preview plus confirm_token) and the full apply protocol. Nothing required to invoke it correctly is absent.

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 50%: confirm_token is well described in the schema itself, while deal_id carries only a regex pattern. The description reinforces confirm_token usage but adds little about deal_id beyond its name, so it neither compensates for the gap nor goes beyond the schema.

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

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

States a specific verb and resource ('Permanently delete a deal') and immediately scopes the blast radius ('follow-ups linked to it are unlinked, not deleted'). That cascade note is exactly what distinguishes it from siblings like upsert_deal or delete_contact, which an agent can differentiate without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit two-call protocol: first call with no confirm_token returns only a preview, then a second call with identical arguments plus the token applies the change, gated on user approval. There is no inference required about when to call which way.

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, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that by stating output is text only and that the server has no send capability, preventing an agent from treating this as an outbound-action tool. It does not mention rate limits or whether drafting leaves any trace in the CRM.

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 action and scoped immediately after by the no-send caveat. Every clause carries information; nothing is restated from the title beyond useful confirmation.

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 six-parameter tool with 0% schema description coverage and no output schema, the description covers the behavioral side adequately (text-only return, no sending) but is silent on the parameter set an agent must fill in. It is minimum-viable: enough to know what the tool is, not enough to call it confidently without guessing at tone/purpose/channel semantics.

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

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

Schema description coverage is 0% across six parameters, so the description must carry the semantic load and does not. It alludes to contact and channel ('email/DM') but says nothing about tone, purpose, key_points, or sender_name, leaving enum choices and constraints unexplained. With three enum parameters and no per-field guidance, an agent gets almost no help beyond the schema's literal names.

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 pairs a specific verb (draft) with a specific resource (email/DM for a contact) and names the data it consumes (CRM deal, last activity). No sibling tool drafts messages, so an agent can separate this from log_activity, add_follow_up, or get_contact without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It establishes clear usage context: use it when you need composed text for a contact, drawing on deal and last-activity context. There is no explicit 'when not to use' or named alternative, but the emphasis that this server cannot send bounds the tool's role well enough for 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?

Annotations already establish the safe read-only, idempotent, closed-world profile, so the description's job is to add context beyond that. It does add real value by disclosing the response composition and an explicit truncation limit of 20 activities, which the annotations cannot convey; it stops short of saying whether that cap is silent or how a missing contact behaves.

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

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

A single front-loaded sentence with no filler. The scope and the activity cap are stated up front, and every clause carries information.

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

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

With no output schema, the description must carry the return-value burden, and it reasonably does by naming the included collections and the activity cap. It is slightly incomplete on edge cases such as nonexistent contacts and whether the deals or follow-up lists are themselves bounded.

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 0%, so the description is expected to compensate for the undocumented parameter, and it does not: contact_id is never mentioned, nor is its c_<hex> format or that it is required. The schema's pattern constraint is the only signal about the parameter's shape.

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

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

The description names the specific resource (a full contact record) and enumerates the associated payload: deals, open follow-ups, and the 20 most recent activities. It implicitly separates itself from list_contacts by being a single, full-detail fetch, but it never names that sibling or any alternative explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the detailed single-contact lookup to use when it already has an ID and needs the full picture, versus list_contacts for browsing. There is no explicit when-to-use, when-not-to-use, or named alternative, so the routing burden falls on inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context that the query spans name, email, company and notes, but says nothing about pagination, default limit, or result ordering.

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

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

A single front-loaded sentence with the resource first and the filterable fields parenthetically grouped. Zero filler; every clause adds 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 read-only list tool with annotations covering safety and no output schema, the description is serviceable but thin: it omits pagination behavior, the significance of the limit cap, default ordering, and whether results are truncated. An agent could call it correctly but not predict result shape.

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 0%, so the description carries the burden, and it does explain the semantics of 'query' (fields searched) and implies 'tag' filtering. However 'limit' is completely unexplained and the tag matching rule (exact vs partial, max 40 chars) is left to the schema's constraints 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?

States a specific verb and resource ('List contacts') plus the filtering dimensions, which clearly separates it from get_contact (single record) and the upsert/delete siblings. It stops short of explicitly naming a sibling or contrasting scopes, so it is clear but not maximally differentiated.

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 word 'optionally' implies the tool works with or without filters, which is implicit usage guidance. There is no statement of when to prefer this over get_contact, no mention that an empty result is normal, and no guidance on combining query with tag.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the useful disclosure that the contact name is included in results, but says nothing about pagination, ordering, or result volume.

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

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

Two short sentences with the action and filters front-loaded; there is no filler. The only weakness is that the same brevity leaves the open_only parameter undocumented.

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 list tool with annotations covering safety and no output schema, a brief description is largely sufficient. However, the undocumented open_only parameter and the absence of any pagination or result-shape guidance leave gaps an agent would need to guess at.

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 0%, so the description must carry the load. It explains stage and contact filtering, but never mentions open_only, and gives no format or semantics for contact_id (the schema supplies only a regex pattern). One of three parameters is entirely undocumented in prose.

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 deals') and names the optional filters, which separates it from siblings like upsert_deal or pipeline_summary. It does not explicitly name an alternative tool, so it stops short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It hints at filtering ('optionally by stage or contact') but never states when to call this versus pipeline_summary (which presumably aggregates) or search-style siblings. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds real behavior: default filtering to open items, sort order by due date, and overdue/due-today flagging. It omits return shape and pagination, but the added flags and ordering justify a 4 over the annotation baseline.

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 waste; the scope and ordering are front-loaded before the parameter hint. Nothing could be cut without losing information.

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

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

For a 3-parameter read tool with no output schema, the description covers default scope and ordering but leaves include_done and as_of behavior unexplained, and says nothing about the shape of results an agent will receive. Adequate but with clear 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 33%: only as_of carries a schema description. The description explains due_within_days' limiting role, which compensates for part of the gap, but include_done semantics and any detail on due_within_days units/edge values are left entirely to inference.

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) and resource (follow-ups) plus the scope: open items only, sorted by due date. The resource name and 'open' qualifier effectively separate it from add_follow_up and complete_follow_up, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use due_within_days to limit' gives one usage hint, and 'Open follow-ups' implies done items are excluded unless include_done is set. There is no explicit statement of when to prefer this over the sibling list tools or when to set include_done, so guidance is only implied.

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

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

Annotations only state that this is a non-read-only, non-idempotent, non-destructive write. The description adds the critical behavioral fact that the first call writes nothing and returns only a preview plus token, which is not derivable from structured fields. It stops short of covering stale/expired tokens or what the preview contains.

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

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

Two tight sentences with zero filler; the write-confirmation constraint is front-loaded immediately after the purpose statement, which is exactly the ordering an agent needs.

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

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

For a mutation tool with no output schema, the description covers the highest-risk unknown (preview-only first call, nothing persisted). It omits token expiry/error behavior and preview contents, which are minor for correct invocation but would complete the picture.

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 only 33%, but the description confirms the key semantics: contact_id is required, deal_id is optional, and the activity type set. The 'at' timestamp and the identifier patterns are left to the schema, so value is added but the coverage gap is only partly compensated. Baseline 3 is appropriate.

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

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

States a specific verb and resource with scope: record a call, email, meeting, DM or note against a contact, optionally a deal. This cleanly distinguishes it from the read tools (list_contacts, get_contact) and the upsert/delete 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?

Gives explicit when-to-use guidance for the two invocation modes: first call without confirm_token to preview, second call with the token after user approval. It does not name any alternative tool (e.g. when to prefer draft_outreach), but the sequencing guidance 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?

Annotations already establish readOnlyHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful context about what is computed, including the stale-deal rule tied to inactivity, but says nothing about cost, freshness, or scope limits of the aggregation.

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

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

A single dense sentence that front-loads the primary metrics and appends the stale-deal qualifier. It wastes no words, though it reads as a fragment without a clear verb.

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 does the job of naming the returned metrics, which is helpful. However, it leaves as_of undefined and gives no sense of how the metrics are scoped (all deals? filtered by owner?), leaving gaps for a zero-required-parameter aggregation tool.

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

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

Schema coverage is 0%: neither parameter is documented in the schema. The description's phrase 'no activity in N days' gives real meaning to stale_after_days, but the as_of parameter — a date the agent must format as YYYY-MM-DD — is entirely unexplained, so compensation is only partial.

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

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

The description names the resource (deals/pipeline) and enumerates the specific outputs — stage breakdown, weighted forecast, win rate, overdue follow-ups, stale deals — which clearly distinguishes it from sibling list tools like list_deals. The verb is implicit ('summary'), but the aggregate nature is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this summary versus list_deals or list_follow_ups, nor any mention of prerequisites. The reporting intent is inferable from the enumerated metrics, but the agent is left to guess the trigger conditions.

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

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

Annotations declare destructiveHint=true but say nothing about the mechanism; the description supplies exactly the missing context: the first call writes nothing and returns a preview plus confirm_token, and nothing is persisted until the token is replayed with identical arguments. That is disclosure well beyond the annotation layer.

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

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

Three compact sentences, front-loaded with purpose followed by the two-step constraint. No filler, and the highest-risk information (nothing is written on the first call) is stated plainly rather than buried.

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

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

With no output schema, the description compensates by describing what the first call returns (a preview and a confirm_token). Together with the partial-update semantics and the confirmation gate, an agent has everything needed to call this mutation 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 only 13%, so the description must carry the load. It does add key semantics for contact_id (selects update mode) and confirm_token (two-step gating) plus the important partial-update rule that 'only provided fields change', but the six field parameters (name, email, tags, notes, phone, company) remain undocumented.

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 specific verb and resource (create/update a contact) and, critically, the rule that selects the mode: update happens 'when contact_id is given'. An agent can distinguish this from delete_contact, get_contact, and upsert_deal without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit operational condition (contact_id present → update; absent → create) and a mandatory workflow (preview first, apply only after user approval). It does not name sibling alternatives or exclusions, so it falls short of a full when/when-not/alternative statement.

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 flag destructiveHint=true and idempotentHint=false, and the description adds genuinely new behavior: the first call writes nothing and returns a preview plus confirm_token. That materially changes how an agent should behave. It does not clarify whether updating with omitted fields clears existing values or what the applied result looks like, which is the main remaining behavioral gap for a destructive mutation.

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

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

Front-loaded with the core action, then the critical TWO-STEP constraint, with zero filler sentences. Every clause either identifies create-vs-update or prevents an agent from accidentally writing on the first call.

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

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

With no output schema, the description correctly explains what the first call returns (preview + confirm_token), which is the essential return behavior. It is nearly sufficient for a mid-complexity mutation tool, though it omits error/failure behavior and the effect of partial updates.

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 only 13%, so the description has to carry the load and it partly does: it explains deal_id's role and reinforces the confirm_token semantics. The other six parameters (stage, title, value, currency, contact_id, expected_close) are left to their patterns/enum in the schema, with no added meaning, so it only partially compensates for the coverage 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?

States both verbs and the resource precisely ('create a deal', 'update an existing deal') and gives concrete update examples (move stage, change value). The conditional 'when deal_id is given' makes the upsert branch unambiguous and clearly separates it from siblings like delete_deal, list_deals, and upsert_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?

Explicitly states the create-vs-update selection rule (deal_id present) and gives a strong procedural instruction for the two-step confirm flow, including telling the caller to show the preview to the user before re-calling. It lacks any 'do not use this when…' exclusions relative to siblings, 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.