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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses scope exclusions (notes are not emails, not the description field), but for a write operation it says nothing about permissions, whether notes are append-only/immutable, notification side effects, or auth requirements. Additive semantics are implied by 'Add' but not stated.

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, each earning its place: purpose first, then the patch_card alternative, then the email anti-pattern. No filler and well 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 4-parameter mutation tool with no output schema, the description covers purpose and routing thoroughly, and the schema handles the projectId authorization nuance. It is slightly short on behavioral disclosure (permissions, idempotency) that annotations would otherwise have supplied, but nothing essential to calling it correctly is missing.

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

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

Schema coverage is 75%: text, title, and projectId are documented in the schema, but cardId has no description anywhere. The description's '(title + body)' merely restates the schema and adds no format, length, or id-sourcing detail beyond it. Baseline 3 fits given 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 and resource ('Add a structured note to a desk card') plus the shape of the payload (title + body). It also explicitly distinguishes itself from siblings patch_card, log_email, and create_status_update, so an agent can route correctly 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?

Gives explicit when-to-use and when-not-to-use guidance: use patch_card with description for the main card description, and do not use notes to log emails (route to log_email or create_status_update with touchpoint values). This is exactly the alternative-routing an agent needs.

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?

No annotations are provided, so the description carries the full behavioral burden, and it is thin. 'Add' implies a write, but it says nothing about required permissions, whether the note is appended, or what the response returns. The 'structured note' phrasing is the only real context beyond the 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?

A single front-loaded sentence with zero waste, naming verb, resource, and payload up front. It is efficient, though its brevity borders on under-specification rather than tight conciseness.

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 annotations and no output schema, the description leaves key behavioral questions open: auth/permission needs, what happens on success, and how it differs from patch_company_note. The schema covers most parameters, but the behavioral envelope is incomplete.

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 75%, and the description's '(title + body)' maps to the title/text parameters, reinforcing the structure. However, companyId has no schema description, and the description only indirectly implies it points to a customer-directory company rather than adding explicit 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?

States a specific verb (add), resource (note), and target scope (customer-directory company), with the parenthetical '(title + body)' clarifying the payload shape. The 'company' target implicitly distinguishes it from sibling add_card_note and add_contact_note, though it does not name them.

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

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

No when-to-use guidance, no prerequisites, and no mention of the natural alternative patch_company_note for editing existing notes. The agent must infer from the name alone that this creates rather than modifies.

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?

With no annotations, the description carries the full behavioral burden but only implies a mutation ('Add'). It says nothing about whether the note appends or overwrites, required permissions, or what happens if contactId is invalid, leaving the agent without meaningful behavioral context for a write 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?

A single front-loaded sentence that wastes no words and puts the action first. It is efficient, though bordering on under-specified rather than optimally informative.

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 note-creation mutation with no annotations and no output schema, the description covers the what but omits the how (auth, project scoping behavior beyond what the schema states, error/return expectations). The fairly detailed projectId schema field partially compensates, keeping this at a minimum-viable 3.

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 75% and the schema already documents title (optional, max 120), text (required), and the nuanced projectId authorization rule. The description's '(title + body)' merely restates two schema params and adds no syntax or format meaning, so baseline 3 is appropriate.

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

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

States a specific verb ('Add') plus resource ('note to a customer-directory contact') and clarifies the payload shape ('title + body'). The contact resource cleanly separates it from siblings like add_card_note and add_company_note, though it never names the update counterpart patch_contact_note.

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 guidance on when to use this versus patch_contact_note, nor any prerequisites (e.g. the contact must exist). Usage is left entirely to inference from the tool name.

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?

With no annotations, the description carries the full burden. It states that cloning produces a new draft (implying the source is unchanged) and that retargeting is optional, but it omits permission requirements and the behavior for omitted fields.

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

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

Three concise sentences, front-loaded with the core action, with no wasted text.

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?

An output schema exists, so return values needn't be explained. However, for a 7-parameter mutation tool with no annotations, the description leaves gaps around projectId context and the customerReference 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 only 29%. The description explains the retargeting purpose of title, opportunityId, companyId, and contactId, but leaves projectId and customerReference unaddressed, so it only partially compensates for the low 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 states a specific verb and resource: 'Clone an existing quote into a new draft.' It does not name sibling tools like create_quote, so sibling differentiation is only implied through the preference note.

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 a clear context for preferring this tool ('when the user likes a past quote') but does not name alternatives or state 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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses none of the mutation profile: no permissions/auth requirements, no idempotency or duplicate-handling, no notification or side-effect behavior, and no statement that the deprecated 'notes' alias should be avoided. The only behavioral hint is the create_case routing preference, which is thin for a 14-param write 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?

Front-loaded with the core action and the key routing rule, packed into two dense sentences with no filler. The long parenthetical enumeration of fields is slightly heavy but each item maps to a parameter, so little is wasted.

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

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

Output schema exists, so return values need not be described, and the schema covers parameter detail thoroughly. However, for a mutation tool with zero annotations, the description omits the authorization and side-effect context an agent needs to call it safely, leaving a meaningful 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 description coverage is 93%, so the schema already documents nearly every parameter with richer detail (stage id rules, currency format, period conversion notes). The description's parenthetical field list largely restates schema content and adds no syntax or format meaning beyond it, which is the baseline-3 case.

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+resource ('Create a desk card') and enumerates the fields it accepts, so the agent knows exactly what the operation produces. It also distinguishes itself from the sibling create_case by preference rule, letting an agent route without opening either 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 actionable context: resolve owners via dealdesk.list_desk_users and prefer estimate fields over create_case when the opportunity already lives on the desk. It names one alternative with a selecting condition, but provides no explicit when-not guidance or prerequisites for card creation itself.

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?

With no annotations, the description carries the full burden, and it does add one valuable behavioral fact: creating a case also adds a desk card. However it says nothing about required permissions, idempotency, or how the created case/card is identified, leaving significant behavioral gaps for a mutation 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?

Three compact sentences with the core action front-loaded and the sibling routing placed after. No filler or redundancy; 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?

For a 12-parameter mutation tool with no annotations, no output schema, and only 42% schema coverage, the description is only partially complete. It handles purpose and the key sibling exclusion well but omits parameter meaning and any return/identification behavior.

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 42% across 12 parameters, so the description is expected to compensate, but it explains none of them (no guidance on stage, ownerUserId, companyId, etc.). The few documented fields (projectId, estimatedValue, probabilityPercent, estimatedValuePeriod) are covered only by the schema, not the description.

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 ('Create a DealDesk case') and immediately disambiguates it from a Salesforce Opportunity search. It also discloses the side effect that a case creation adds a desk card, so the agent knows exactly 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?

Explicitly names the alternative dealdesk.patch_card for setting value/chance/period on an existing desk card and warns 'do not create_case as a substitute.' That is a clear when-not, but it does not cover the broader create landscape (e.g., create_case vs create_card) among the many 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?

With no annotations, the description carries the full burden. It does disclose non-obvious server behavior: 'name' is aliased to 'legalName' server-side and externalId is auto-generated as local-company-<uuid> when omitted. However it says nothing about permissions required, whether creation is reversible, duplicate handling, or what happens to fields.legalName vs top-level conflicts beyond a hint.

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 action, then the two highest-value calling gotchas (alias mapping and auto-generated externalId). No filler, though the em-dash clause about fields.externalId is slightly awkward 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 a 10-parameter mutation tool with no annotations and no output schema, the description covers the two most likely failure modes (which name field to send, omitting externalId) but omits practical concerns like the conditional requirement of projectId when multiple projects are authorized, and any response/identity information for the created company.

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 60%, so the schema documents some fields but the description must add meaning. It usefully clarifies the name/legalName alias and the externalId auto-generation default, but leaves taxId, locale, registrationId, emailDomains, and displayName without added context, and does not state that legalName or name is effectively required.

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

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

States a specific verb and resource ('Create a company in the customer directory'), which is clearly distinct from create_contact, create_case, and create_quote among the siblings. It stops short of naming any sibling or stating explicit boundaries, so it is clear but not differentiating.

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 guidance on when to use create_company versus patch_company or get_company/list_companies, nor on prerequisites such as required auth scope. The only 'use this way' advice is about request shape, which is parameter semantics rather than invocation context.

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

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

No annotations are provided, so the description carries the full behavioral burden. It says nothing about permissions, whether creation is idempotent, what happens on duplicate email/externalId, or what the tool returns. The auto-generation note on externalId is behavioral but is already repeated in the 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 short sentences, front-loaded with the action and immediately followed by the required-field rule and the optional externalId behavior. No 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 9-property mutation tool with no annotations and no output schema, the description covers the essential naming rule but omits permissions, error/duplicate behavior, and any note on the multi-project projectId requirement (left entirely to the schema). 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 56%, and the description adds a genuine cross-field constraint not expressed in the schema: displayName or name (or firstName/lastName) is required despite zero formally required parameters. Otherwise it largely restates the externalId auto-generation behavior already documented in the schema, leaving other params (locale, projectId, fields) to 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+resource ('Create a contact in the customer directory'), which cleanly separates it from siblings like create_company, patch_contact, and get_contact. It does not explicitly name a sibling, but the create-vs-patch-vs-get distinction is obvious from the name/verb pairing.

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 guidance on when to use this versus alternatives (e.g., patch_contact for editing, or when a contact already exists). The only conditional content is about required fields, which is parameter semantics, 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?

No annotations exist, so the description carries the full behavioral burden. It adds some meaningful context ('draft' state, server-side snapshot resolution), but says nothing about permissions/scopes, idempotency, or what happens to unresolved references — significant gaps for an 11-parameter mutation 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?

Three tight sentences with zero filler; the create action, the server-side guidance, and the sibling routing are front-loaded in that order. 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?

An output schema exists, so return values need no explanation, and the description covers purpose, alternative routing, and key parameter advice. It stops short of disclosing auth requirements or failure behavior for a complex nested-object tool, which keeps it from a 5.

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 64%, so the schema already documents most parameters. The description adds real meaning for companyId/contactId (server-side snapshot resolution) but leaves other parameters (currency, language, opportunityId, projectId) entirely to the schema. A 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 ('Create a classic draft quote') and immediately scopes what it produces (lineItems, options, groups). It explicitly distinguishes itself from the sibling create_quote_from_configuration by labeling itself the CPQ-free / free-form path.

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 routing rule: 'Use this path for free-form / open positions; use create_quote_from_configuration for CPQ.' It also advises preferring companyId/contactId so snapshots resolve server-side, giving both a when-to-use and how-to-call condition.

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?

With no annotations, the description carries the full disclosure burden. It usefully reveals that quoteLayout only shapes presentation and that commercial amounts 'stay server-evaluated' (server-side computation, not client-supplied) - valuable context. However, it omits permission requirements, the failure mode for unpublished configurations, and mutation/irreversibility details for what is clearly a write 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?

Two compact sentences with the core action front-loaded and no wasted wording. The second sentence adds constraints efficiently, though the phrasing ('shapes groups/optional/editable presentation') is dense enough to border on terse.

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, nested objects, and no annotations, the description is thin. An output schema exists so return values needn't be explained, but prerequisites ('published' configuration), the relationship between configuration/priceBookRevisionId, and behavioral expectations for a CPQ quote creation are left unaddressed.

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 25% across 12 parameters, so the description needs to compensate but largely does not. It clarifies quoteLayout's presentational role and that amounts are server-evaluated, but says nothing about title, locale, currency, language, companyId, contactId, customerReference, portfolioRevisionId, or priceBookRevisionId, leaving most parameters 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 a specific verb and resource ('Create a quote') and names the source mechanism ('from a published Portfolio configuration (CPQ)'), which meaningfully separates it from the plain create_quote and clone_quote siblings. It stops short of explicitly naming those alternatives, but an agent can still distinguish the CPQ-driven path from a plain quote creation.

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 via the phrase 'from a published Portfolio configuration,' which hints at the prerequisite that a published configuration must exist. There is no explicit when-to-use/when-not guidance nor any naming of create_quote, clone_quote, or update_quote_from_configuration as alternatives, leaving the choice to 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?

With no annotations, the description carries the full burden and does disclose useful traits: the two returned link types (classicPath, experiencePath), the soft-close mechanism, and the absence of a delete path. It omits permission/auth requirements, whether the link is immediately live, and password enforcement behavior.

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 action, then return values, then lifecycle constraints. No filler; every sentence 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?

No output schema exists, so disclosing classicPath/experiencePath is genuinely necessary and provided. However, for a 5-parameter mutation with no annotations and 40% schema coverage, key context (auth/project scoping, password behavior, quickchatEnabled semantics) 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 40% (label, quoteId, and quickchatEnabled are undocumented), and the description compensates for none of it — it never explains label, password, quickchatEnabled, or projectId. The agent must infer all parameter meaning 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?

States a specific verb and resource ('Create a customer share link for a quote') that an agent can immediately distinguish from siblings like list_quote_shares, patch_quote_share, and create_quote. The scope 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?

It routes the agent clearly for the follow-up lifecycle: 'Soft-close later with patch_quote_share isOpen=false' names the alternative tool and the exact operation, and it warns that delete is unavailable through MCP. It stops short of stating when creating a share is or isn't appropriate (e.g. prerequisites on quote state).

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?

No annotations are provided, so the description carries the full behavioral burden, and it says nothing about side effects: whether comments notify mentionedUserIds, whether tasks are assigned/reminded, whether recurrence spawns future records, or what permissions/project scoping the create requires. For a 21-parameter mutation tool this leaves the agent guessing about consequences.

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

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

Two sentences, front-loaded with the core action and subtypes, then the routing rule. Every clause carries information and nothing is padded.

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

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

For a mutation tool with 21 parameters, 4 enums, no annotations and no output schema, the description omits any explanation of how the many optional fields interact (e.g., comment vs task vs touchpoint field requirements, project authorization) and gives no notion of the result. It is too thin for this complexity.

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 76%, so the schema already documents most parameters (from/to, body, note, dueAt, touchpointType, occurredAt, participants). The description only restates the touchpoint enum, adding no new meaning; 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+resource (create a status update) and immediately enumerates the three subtypes (comment, task, touchpoint) plus the touchpoint enum values. It also names the sibling it is not (dealdesk.log_email) and the condition that selects that sibling, so an agent can distinguish it 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?

Provides one explicit routing rule: prefer dealdesk.log_email for inbound/outbound email logs. That is a genuine when-to-use-alternative statement, but there is no guidance on choosing between comment, task and touchpoint, nor on prerequisites such as project scoping or permissions.

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?

With no annotations, the description carries the full burden. It usefully discloses a non-obvious side effect ('unlock skill-gated tools for one domain') and a return field ('authorizedProjectIds'), which is meaningful because this is not a pure read operation. However, it does not say whether unlocking is permanent, what permissions or skill gating are needed, or whether projectId selection affects the unlock.

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 clauses with zero filler, front-loaded with the primary action and followed by the secondary effect, the extra return field, and the sibling disambiguation. 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 two-parameter discovery tool with no annotations or output schema, the description covers the core action, the side effect, and one returned field. It is missing what the domain listing returns and the sequencing relationship to the gated domain tools it unlocks, which is the main remaining 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 description coverage is 100%, so both parameters (domain, projectId) are already documented in the schema, including the omission semantics. The description adds only a partial domain enumeration and no extra syntax or behavioral detail beyond the schema, 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?

States a specific verb+resource ('List additional DealDesk tool domains') and adds a second function ('unlock skill-gated tools for one domain'). It enumerates most domains, though the list is incomplete versus the schema enum (omits portfolio-authoring and export), and it explicitly routes away from dealdesk.list_projects.

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 one explicit alternative and condition: 'Prefer dealdesk.list_projects to list Connect projects.' It implies the omission behavior for domain via the schema ('Omit to list domains only'), but never states when an agent should call discover at all (e.g., before invoking domain-gated 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?

No annotations exist, so the description carries the full burden, yet 'Bounded export path' is left undefined and gestures at a constraint without explaining it. It says nothing about auth requirements, whether the export is synchronous, size limits, or what the bounded path actually restricts.

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?

It is short and front-loaded, which is good, but the second sentence ('Bounded export path') is cryptic and does not earn its place given it conveys no 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 annotations and no output schema, the description must explain the result and behavior, but it does not describe what the workbook contains, where the file lands, or how the caller retrieves it. For an export tool this leaves key operational questions unanswered.

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 67% and the description adds no parameter meaning at all. The 'source' enum (intelligence/board) has no description in the schema and gets no explanation in the description, so the gaps are unaddressed.

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 (Export) and resource (Deal Intelligence workbook, Excel) with the output format named, which is clear. It is distinguishable from the list_/get_ siblings, though the trailing 'Bounded export path' adds no clarity.

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 only 'for analysis' as context and never states when to use this export versus the many list_/get_ alternatives for the same DealDesk data. No exclusions or prerequisites are offered.

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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it says nothing about permissions, error/not-found behavior, or what happens when projectId is omitted and multiple projects are authorized. It only implies a read by virtue of the verb 'Get'.

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 short sentence with the key constraint ('one', 'by id') front-loaded and no wasted words. It is efficient, though arguably under-specified rather than deliberately terse.

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?

An output schema exists so return values need not be explained, but with no annotations and a near-empty description the agent gets no behavioral context: no auth requirements, no failure modes, and no guidance on the optional projectId beyond the schema. It is minimally workable but leaves 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 50%: projectId is documented in the schema, but cardId has no schema description, and the description's 'by id' adds no format or sourcing detail. With half the parameters undocumented, the description fails to compensate 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?

The description states a specific verb ('Get') and resource ('desk card') scoped to a single record, which implicitly distinguishes it from the sibling list_cards. However, it does not explicitly name that alternative or otherwise differentiate itself from the many other get_* tools in the family.

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 when-to-use guidance, no mention of prerequisites, and no pointer to an alternative such as list_cards when the caller does not have an id. The agent must infer the usage context entirely from the name.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about permissions, auth scoping, or what happens when the id does not resolve. Only the schema's projectId description hints at an authorization model.

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 short sentence with zero padding and the key lookup verb front-loaded. It is appropriately sized for a read-by-id operation, though the brevity reflects under-specification rather than disciplined economy.

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 operation with no output schema and no nested structures, the minimum viable information is present. Still missing are error behavior on an unknown id and any note that the returned payload is a full case object.

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 50%: projectId is well documented in the schema, but caseId has no description. The phrase 'by id' only restates that caseId identifies the case and adds no format, validation, or scoping detail 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 (Get) and resource (a DealDesk case) with a clear scope qualifier ('one ... by id'), which implicitly distinguishes it from the sibling list_cases. However, it offers no differentiation from other single-resource getters in the sibling set such as get_card, get_company, or get_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?

There is no guidance on when to use this tool versus list_cases or another get_* sibling, nor any stated prerequisites or conditions. The agent must infer usage entirely from the name.

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?

With no annotations, the description carries the full behavioral burden, and it does almost nothing: no statement about read-only safety, permissions, or behavior when the id is unknown. 'Get' weakly implies a read, but nothing is disclosed about errors, authorization, or the multi-project ambiguity the projectId parameter hints at.

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 single sentence is front-loaded and free of waste, but it is so terse that it barely earns its place as documentation; brevity here reflects under-specification rather than disciplined conciseness.

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 2-parameter lookup with no output schema, the description should at least clarify what is returned and how a missing/unauthorized company is handled. Neither is present, leaving real gaps for an agent invoking it.

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%: companyId has no schema description and the description adds nothing about it beyond 'by id'. The projectId semantics (omit vs required depending on OAuth authorization) live entirely in the schema, and the description does not reinforce or clarify either parameter.

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 (get) and resource (company) scoped by id, so an agent can tell it retrieves a single company. However, it offers no differentiation from siblings like dealdesk.list_companies or dealdesk.get_company_commercial_summary, which could also return company data.

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 guidance on when to use this versus list_companies, get_company_commercial_summary, or patch_company. The agent must infer retrieval-vs-list behavior purely from the name.

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?

No annotations are provided, so the description carries the full disclosure burden. It implies a read operation and lists data categories, but says nothing about permissions, whether values are aggregated vs raw, currency, time window, or pagination behavior.

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 sentence with zero filler that front-loads the primary output (pipeline value) before secondary linked records. Appropriately sized for the amount of information conveyed.

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 annotations, no output schema, and half the parameters undocumented in the schema, the description should be doing far more work. An agent cannot tell what the return shape looks like, whether projectId is needed for its token, or what 'open/won/lost' is measured against.

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%: projectId is documented in the schema but companyId is not. The phrase 'for a company' weakly implies companyId, and the description adds nothing about the project-scoping rules already stated in the schema.

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

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

States a clear verb (get) and resource (commercial summary) and enumerates the returned content: open/won/lost pipeline value plus linked deals, quotes, and orders. It does not explicitly distinguish itself from the sibling dealdesk.get_contact_commercial_summary, leaving the company-vs-contact scope to inference.

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, no prerequisites, and no alternatives named. The presence of closely related siblings (get_contact_commercial_summary, portfolio_summary, get_quote_summary) makes the absence of routing guidance 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?

With no annotations, the description carries the full behavioral burden and delivers almost nothing: it does not state permission requirements, behavior when the id is unknown, or what shape of record comes back. 'Get' implies a read, but that is inferred, not 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?

A single front-loaded sentence with no filler; nothing needs to be trimmed. Its brevity is not a structural flaw, though it leaves the definition sparse.

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 read tool with no output schema, the essentials are mostly covered: the schema explains the projectId omission rule. However, with no annotations and a thin description, an agent gets no signal about auth scope, failure modes, or the returned record, leaving a meaningful 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 only 50%: projectId is well documented in the schema, but contactId has no description anywhere. The description's 'by id' is the only hint that contactId is an identifier, and it adds nothing about the multi-project authorization rule that projectId encodes.

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 (Get), resource (contact), and scope (one, by id), which cleanly separates it from list_contacts and get_company. It does not explicitly distinguish itself from the similarly named get_contact_commercial_summary, 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?

There is no guidance on when to use this versus list_contacts (to find an id) or get_contact_commercial_summary (for enriched data). The phrase 'customer-directory contact' hints at scope but no alternative or condition is named.

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?

No annotations are provided, so the description carries the full behavioral burden. It implies a read-only aggregation but says nothing about permissions, whether values are live or cached, currency/date handling, or pagination limits on the linked deals/quotes/orders.

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 wasted words. It is arguably too terse for a tool with auth-scoped parameters, but nothing is 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?

There is no output schema, so the one-line enumeration of returned data does useful work, and the projectId scoping rule is covered elsewhere. Still missing are the auth/project authorization expectations and any sense of the shape or size of the linked deals, quotes, and orders returned.

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%: projectId is well documented in the schema (including exactly when it is required), while contactId is only self-evident by name. The description adds no parameter detail, so it neither compensates nor undermines — baseline 3 for a two-param tool at half 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?

States a specific resource and enumerates exactly what it returns: open/won/lost pipeline value plus linked deals, quotes, and orders for a contact. This lets an agent distinguish it from the sibling get_company_commercial_summary and get_contact, though the description never names those alternatives 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?

No guidance on when to use this versus siblings such as get_contact, get_company_commercial_summary, or portfolio_summary. The agent must infer the use case purely from the output contents listed.

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?

No annotations are provided, so the description carries the full burden. 'Get' implies a non-mutating read, but nothing is said about authentication/authorization requirements, whether response shape varies by the classic vs rich/experience path, quota limits, or what the share links actually are. The path distinction is mentioned but never characterized.

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 trailing parenthetical is slightly cryptic and would have been better spent on routing guidance, but the sentence is efficient.

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?

An output schema exists, so return values need not be respecified — yet the description spends its words enumerating them anyway. Given a crowded quote-tool namespace and no annotations, the description leaves the key gaps (when to choose this over get_quote_summary, and the meaning of quoteId) unaddressed.

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 50%: projectId is well documented in the schema, but quoteId has no description anywhere, and the description adds no parameter meaning at all. A GET-by-id tool should at minimum clarify that quoteId is the canonical identifier, especially given multiple sibling id conventions (card, company, contact, case).

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?

Specific verb 'Get' + resource 'quote' with an enumeration of the payload (status, totals, acceptance summary, analytics, share links). It is distinguishable from write siblings like patch_quote or create_quote, but it does not differentiate itself from near-neighbors such as get_quote_summary, render_quote_totals, or list_quote_shares, which appear to return overlapping data.

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 statement of when to use this tool versus the many quote siblings (get_quote_summary, list_quotes, list_quote_shares, render_quote_totals). The agent must infer usage from the name alone, and the '(classic + rich/experience paths)' parenthetical is never explained as a selection criterion.

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?

No annotations are provided, so the description carries the full burden. It does add real behavior context: read-only, returns persisted data, and explicitly does no enrichment or repricing (unlike render_quote_totals). However, it omits auth/permission needs and any side-effect or error behavior for a project-scoped read.

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 wasted words; the verb and resource lead, with the key scoping qualifier at the end. Every clause 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?

An output schema exists, so return values need not be explained, and only two parameters are involved. But with no annotations and only one sentence, the definition leaves gaps on when to choose this over get_quote or render_quote_totals and on how quoteId is sourced.

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 50%: projectId is well documented in the schema, but quoteId has no schema description. The description adds nothing about either parameter (e.g., where to obtain quoteId, required vs optional), so it fails to compensate for the quoteId 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 a specific verb ('Read') and resource ('quote line items/options/groups and status') with the scoping qualifier 'persisted'. The 'without enrichment or repricing' clause hints at differentiation from get_quote/render_quote_totals, but it doesn't name those siblings, so an agent must infer the boundary.

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 phrase 'without enrichment or repricing' implies when this tool is appropriate (raw persisted data rather than computed/enriched output), but there is no explicit when-to-use, when-not, or named alternative among the many quote siblings. Usage is implied rather than stated.

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

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

With no annotations, the description carries the behavioral burden but does supply real traits: it is a read operation, results are 'persisted' and returned 'Newest first', and 'Empty history is valid' pre-empts a false error interpretation. It omits pagination/limit behavior for a list endpoint, which is the main remaining gap.

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, front-loaded with the core purpose and the covered-event list before the ordering, edge-case, and disambiguation notes. Dense but every sentence carries information; only the parenthetical enumeration is slightly long.

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?

No output schema exists, so the description must convey return content, and it does by enumerating the event types and stating ordering and the empty-case behavior. The missing pagination/limit detail and undocumented cardId keep it from being fully 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 only 50%: projectId is well documented in the schema while cardId has no description. The description implies cardId context ('desk-card change history') but adds no syntax, format, or sourcing detail beyond the schema. This meets the baseline for partial coverage without compensating for the undocumented cardId.

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 (Read) and resource (persisted desk-card change history) and enumerates the change categories covered (stage/owner/account/contact, notes, quote/order/share milestones). It also explicitly distinguishes itself from the status-update timeline, so an agent can separate it from list_status_updates without inspecting the 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?

Provides a clear routing rule by naming the contrasting sibling ('Distinct from status-update timeline (comments/tasks/emails)'), which tells the agent which tool to pick for which kind of activity. It stops short of stating explicit when-not conditions or prerequisites (e.g., needing an existing card), but the alternative is clearly signaled.

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?

With no annotations, the description carries the full burden. It discloses return shape and pagination (total, hasMore, nextCursor) and hints at authorization via projectId/authorizedProjectIds, but it never explicitly states this is a read-only, non-mutating operation, nor notes rate limits or permissions. Useful but incomplete for an unannotated 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?

Four tight sentences with no filler, and the core purpose is front-loaded. The final return-values sentence is dense but earns its place given there is no output schema.

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

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

For a 7-parameter read tool with 100% schema coverage and no output schema, the description supplies the missing return-value context (pagination fields, project scope) and the default row shape. An agent has enough to invoke it correctly; only explicit read-only and error/auth behavior are 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 100%, so the schema already documents every parameter and the baseline is 3. The description adds meaning beyond it by enumerating the default summary row fields (cardId, title, stage, quoteId) and clarifying the summary-vs-full switch — information not present in the schema.

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

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

States a specific verb and resource (list DealDesk desk cards) plus the scope (one project), which contrasts with the sibling get_card for a single card. It is clear but never explicitly names or distinguishes itself from the sibling listing tools (list_desk_stages, list_quotes, etc.), so it stops short of a 5.

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 tells the agent how to narrow results ("Filter with q, stage, and/or ownerUserId") and how to expand them ("Pass fields=full"), which implies usage. However, it gives no explicit when-to-use/when-not guidance and does not name alternatives such as get_card or list_desk_stages as the path for other needs.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about pagination, result size, read-only nature, rate limits, or how the projectId authorization nuance affects behavior. The projectId schema hint is the only auth-related context, and the description does not reinforce or extend it.

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 single sentence is front-loaded with the core action and resource and contains no wasted words. It is appropriately concise for what it chooses to say, though the brevity leaves the definition under-specified for its six-parameter surface.

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 list tool with no annotations, no output schema, and very low schema description coverage, the description is far too thin. It omits filter semantics, pagination behavior, default limits, and the multi-project authorization context that the projectId parameter hints 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 only 17%, so the description must compensate for five undocumented parameters. Instead it says only 'optional filters,' which does not explain what q, type, stage, limit, or ownerUserId actually filter on, nor their accepted values or mutual behavior.

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 ('DealDesk cases'), which is enough to distinguish it from get_case, create_case, patch_case, and the other list_* resources by noun. However, it does not differentiate itself from the other list tools beyond the resource name and adds no routing guidance, so it stops short of a 5.

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 when-to-use guidance, no alternatives, and no conditions under which this list tool is preferable to get_case or the other list_* tools. It merely notes that filters are optional, which is already apparent from the schema having no required parameters.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about pagination, default/max result counts, sort order, whether 'q' matches name vs domain, or the shape of the result. For a search/list endpoint with zero annotation coverage this is a substantial gap.

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 short sentence with no wasted clauses, which is well front-loaded. It is arguably too terse for a 3-parameter tool, so concision here shades into under-specification.

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

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

With no annotations, no output schema, and two of three parameters undocumented, the description would need to compensate and does not. An agent cannot tell result count, paging behavior, or search semantics before invoking.

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% – only projectId is documented in the schema, while q and limit have no description anywhere. The description adds no meaning about what q searches or what limit defaults to, so the undocumented parameters are left entirely to guesswork.

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 recognizable verb+resource (search/list companies) and scopes it to the 'customer-directory', which loosely separates it from sibling list tools like list_contacts or list_projects. However it never names the distinguishing sibling (get_company for a single company) and 'Search or list' leaves the duality of the operation unresolved.

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, no exclusions, and no pointer to alternatives such as get_company or create_company. The agent must infer from the name alone whether this is the right tool for a lookup versus a directory enumeration.

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?

No annotations are provided, so the description carries the full behavioral burden, yet it discloses nothing about authorization scope, pagination, default result size, or read-only semantics. The only auth-relevant text (projectId's multi-project requirement) lives in the schema, not the description.

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. It is efficient, though its brevity contributes to the missing guidance rather than being a virtue of economy.

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 tool with no annotations, no output schema, and only one-third schema coverage, the description is far too thin. An agent cannot determine result shape, auth requirements, or search semantics from what is given.

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% (just projectId), and the description adds no parameter meaning for 'q' or 'limit'. It neither explains the search matching behavior nor how 'limit' interacts with the maximum of 100.

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 pair ('search or list') and resource ('customer-directory contacts'), which is enough to separate it from list_companies or create_contact. However, it does not articulate the distinction between the search mode and the plain list mode, nor differentiate it from near-neighbors like list_desk_users.

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 indication of when to use this versus siblings such as list_companies, get_contact, or the create/patch contact tools. The agent must infer usage entirely from the name and the presence of a 'q' parameter.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the return shape (discrete stages with an order field) and warns against fabricating ids, but omits pagination, ordering guarantees, or authorization behavior beyond what the schema implies.

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: purpose first, then the prerequisite usage, then the anti-pattern guard. Every sentence earns its place with no 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 one-parameter list tool with no output schema, the description covers purpose, precondition, and the id-format pitfall. Only minor gaps (ordering of results, error behavior) remain, which are low-value here.

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

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

Schema description coverage is 100% and the single projectId parameter is fully documented there (including the OAuth multi-project condition). The description only alludes to it via 'the project's', so it adds no meaning beyond the schema – baseline 3.

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) plus the exact resource (desk board stages/columns) and even enumerates the returned fields (columnId, label, labelDe, order). The resource is unique among the many list_* siblings, so an agent can distinguish it 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?

Explicitly states when to use it ('before setting stage on create_card / patch_card / create_case / patch_case') and names the concrete consuming tools. It also gives a clear negative instruction ('Never invent stage ids by slugifying UI labels'), which is exactly the failure mode an agent would otherwise fall into.

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?

No annotations are provided, so the description carries the burden. It discloses the eligibility filter (card/case owners) which is genuine behavioral context, but says nothing about pagination, scoping behavior across projects, or permissions. For a simple read-only list this is acceptable but not rich.

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, zero waste, and the operation is front-loaded before the usage instruction. Every clause earns its place.

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

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

With no output schema, the description usefully enumerates the returned fields and explains the tool's role in the owner-assignment workflow. It omits pagination/ordering behavior, which is the only notable gap for a list endpoint.

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

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

Schema description coverage is 100% and the projectId parameter already documents the omit-vs-required rule for multi-project tokens. The description adds no parameter-level meaning, so baseline 3 is correct.

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 DealDesk users) and narrows scope to those eligible as card/case owners, which distinguishes it from sibling list tools like list_skills and list_contacts. It even names the columns returned (userId, email, displayName).

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 says to use it before setting ownerUserId, and names the four downstream tools (create_card, patch_card, create_case, patch_case) that depend on it. This is exactly the when-to-use guidance an agent needs to sequence calls 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?

There are no annotations, so the description carries the full burden. It usefully discloses the auth model (Connect token or API key) and that no projectId is required, but says nothing about return volume, empty results, or pagination for a discovery-style list.

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, purpose first and the when-to-call condition second, with no redundant restatement of the name or title.

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 discovery tool with no output schema, the description covers what it returns (project ids), its auth basis, and when to use it. Only minor gaps around result shape remain.

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

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

The tool takes zero parameters, so the baseline is 4. The description still adds value by clarifying that no projectId is needed, which pre-empts an agent trying to scope the call unnecessarily.

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 DealDesk project ids) plus the authorization scope (current Connect token or API key). It is unambiguous, though it does not explicitly contrast itself with sibling list tools such as list_companies or list_cards.

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 a concrete trigger: call this before project-scoped tools when more than one project may be authorized. That is clear routing guidance with a real condition, but it names no alternative tool or negative case.

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?

No annotations are supplied, so the description carries the full behavioral burden and largely fails to. It never states that this is a read-only operation, says nothing about default or maximum page size behavior despite the limit parameter, and does not describe ordering or what a result row 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?

A single tightly written sentence that front-loads the resource and then the modifier. Nothing is repeated or padded, and there is no filler to remove.

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 four-parameter list tool with no output schema and no annotations, an agent still lacks pagination semantics (default limit, truncation), result ordering, and confirmation that the call is side-effect free. The authorisation caveat for projectId survives only in the schema, not the description, so the definition is adequate but incomplete.

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 75%, with inline descriptions for q, status, and projectId (including the important single-project authorisation nuance), so the baseline is 3. The description merely restates the status and search filters already documented in the schema and adds nothing for limit or projectId.

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 gives a specific verb+resource ('List quotes') plus the scoping dimension ('for a project'), which cleanly separates it from get_quote, create_quote, and the render_* siblings. It stops short of naming a sibling to differentiate from, so it does not reach a 5.

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 phrase 'optionally filtered by status or search text' implies when the filters are worth using, but there is no explicit when-to-use guidance, no when-not condition, and no pointer to alternatives such as get_quote for a single quote or get_quote_summary for aggregates.

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?

With no annotations, the description carries the full burden. It hints at returned data by naming classicPath and experiencePath, adding some behavioral context, but it does not disclose permission requirements, whether shares are always present, pagination, or the auth implications of the projectId scoping.

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, front-loaded sentences with no filler. Front-loading the purpose before the classicPath/experiencePath detail is good structure, though those two terms are cryptic and unexplained.

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 small read tool with no output schema, the basics are present, but with 50% schema coverage the description should clarify the required quoteId and what classicPath/experiencePath represent. It leaves the agent with an under-explained return 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 only 50%: projectId is documented in the schema but quoteId is not. The description never mentions quoteId or projectId, so it fails to compensate for the undocumented required parameter. It adds no parameter 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 customer share links for a quote"), which is distinguishable from the mutation siblings create_quote_share and patch_quote_share. It doesn't explicitly name siblings, but the read/list scope 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?

Usage is only implied: the tool lists share links for a given quote. There is no explicit when-to-use guidance, no mention of alternatives (e.g., get_quote), and no conditions or exclusions. Adequate but thin.

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?

With no annotations, the description carries the full burden. It discloses one useful behavioral trait — the return payload is auth-scoped project ids ('Returns authorizedProjectIds') — but never states that this is a side-effect-free read or mentions any constraints on invocation.

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, purpose first, return value second; nothing is padded. It is terse to the point of being thin, but 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?

There is no output schema, so the description must cover return values, and it does so only partially — 'Returns authorizedProjectIds' does not explain the shape or contents of the skills list itself, which is the tool's primary output. Adequate for a one-parameter list tool, but leaves a real 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 description coverage is 100% and the single projectId parameter is fully documented in the schema, including the omission rule. The description's mention of authorizedProjectIds weakly reinforces the authorization semantics but adds no syntax or format detail beyond the schema. 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?

States a specific verb ('List') and a specific resource ('shipped DealDesk sales skills packaged with dealdesk-plugin'), which clearly distinguishes it from the many list_* siblings that cover projects, cards, companies, and quotes. It does not explicitly name a sibling it competes with, so it stops short of a 5.

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 statement of when to call this tool, no prerequisites, and no alternatives. The one hint of usage context ('Omit when the OAuth token... authorizes exactly one project') lives in the schema, not the description.

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?

No annotations are provided, so the description carries the full burden. It indicates the kinds of items returned (comments, tasks, touchpoints including email), but does not disclose pagination behavior, permissions, ordering, or other operational traits an agent may need.

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 definition is a single, front-loaded sentence with no wasted words. It states the core action and scope immediately.

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 scope and entity types, which matches the higher-level purpose. However, with no annotations and no output schema, it leaves behavioral gaps around pagination, return shape, and selection relative to siblings, making it only minimally 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 description coverage is 80%, so the schema already documents most parameters, including entityType, entityId, cardId, and projectId. The description adds no parameter-level details beyond what the schema provides, making the baseline 3 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 gives a specific verb ('List') and resource ('status updates'), and clarifies the scope as desk cards, companies, or contacts. It does not explicitly distinguish itself from related siblings such as list_card_activity or create_status_update, so sibling differentiation is only partial.

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 states what can be listed but gives no explicit when-to-use guidance or alternatives. It does not explain when to choose this tool over list_card_activity, get_card, or other related status update endpoints.

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?

With no annotations, the description carries full burden. It does disclose the key side effect (creates a status-update touchpoint on the card and persists structured from/to plus subject/text), which is meaningful. However, it says nothing about auth/project scoping behavior, idempotency/deduplication, or what a repeat log does, leaving real behavioral gaps.

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 purpose, then persistence behavior, then the exclusion rule. Every sentence earns its place with no filler.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers purpose, side effect, and sibling routing adequately, and the rich schema fills parameter details. Remaining gaps (result shape, project-scoping behavior) are minor given the schema coverage.

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 90%, so the schema already documents from/to/subject/text/direction/cardId/projectId. The description largely restates this (from/to plus subject/text) and adds little syntax or format detail beyond it. 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 (log) plus resource (inbound/outbound email) and the exact target object (desk card as a status-update touchpoint). It also names the sibling it is not (add_card_note), letting an agent disambiguate 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?

Provides an explicit anti-use rule ('Do not use add_card_note for email logs') that routes the agent away from the wrong sibling, and the opening clause implies when to use it. It stops short of contrasting with create_status_update or stating prerequisites, so it is a strong but not exhaustive usage 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?

With no annotations, the description carries the full burden and does disclose non-obvious side effects: company/contact or owner changes cascade to a linked local case and quote customer/owner link, estimates update the linked local case when present, dealValueOverride is ignored after accept/decline/order, and there is no DELETE (soft close via stage closed). It omits auth/permission requirements and error behavior, but the mutation semantics are unusually well covered.

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 and the field list, then progressively narrower caveats. It is a dense single paragraph with some run-on clauses, but nearly every sentence carries distinct operational information rather than 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 17-parameter mutation tool with no annotations and no output schema, the description covers the critical unknowns: cross-entity side effects, null/clear behavior, quote-card-only constraints, and the soft-close convention. Return-value expectations and partial-patch semantics are left implicit, which is the main remaining 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 88%, so the baseline is 3, but the description adds genuine meaning beyond the schema: null-clearing semantics for company/contact/owner, the equivalence of companyId/contactId to HTTP accountRef/contactRef, the distinction between estimatedValue (working forecast, does not rewrite quote totals) and dealValueOverride/OverrideNet (unaccepted quote cards only), and that dealValueOverrideNet implicitly sets the flag.

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+resource ('Update a desk card') and enumerates the mutable field groups, which cleanly separates it from siblings like patch_case, patch_quote, and patch_card_note. The follow-up sentences reinforce the boundary by explicitly warning 'Do not call create_case to set estimates on an existing 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?

Gives concrete usage conditions: pass companyId/contactId to link Customer Directory records, pass null to clear, dealValueOverride applies only to unaccepted quote cards, and soft-close uses stage closed. It does not explicitly state when to prefer patch_card over patch_case/patch_quote in ambiguous cases, so it falls short of a full when/when-not/alternative treatment.

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?

With no annotations, the description carries the full behavioral burden. It usefully discloses the concurrency mechanism (updatedAt) and the unavailability of delete, but says nothing about permission requirements, what happens on a stale/expectedUpdatedAt mismatch, or the response shape for a 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?

Two tightly written sentences, zero filler, with the operation and the key prerequisite 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 6-parameter mutation tool with no annotations and no output schema, the description covers the prerequisite and concurrency token but omits permission/error context and the result of the call. It is adequate against the rich schema but leaves behavioral 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 83%, so structured fields already document most parameters, including projectId and text. The description reinforces the source of noteId and updatedAt ('from get_card'), adding modest value over the schema but not compensating for the undocumented cardId field.

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+resource ('Update an existing structured desk-card note'), which cleanly distinguishes it from add_card_note (creation) and the read-only get_card. It does not explicitly name its closest siblings (patch_company_note, patch_contact_note), but 'desk-card note' scopes the target adequately.

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 a clear prerequisite ('Prefer get_card first for noteId and updatedAt') and an explicit exclusion ('Delete is not available through MCP'). It stops short of naming add_card_note as the alternative for creating notes, but the 'existing' qualifier implies that 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?

No annotations are provided, so the description carries the full burden. It discloses useful cross-object behavior (patch_card updates the linked case when one exists), but never states permission/auth requirements, whether updates are partial or full replacement, reversibility, or what happens to omitted fields on a 13-param mutation. Some behavioral value beyond structured data, but with no annotation coverage the gap is notable.

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 verb+resource and field list, followed by the sibling routing rule. No filler. Could be marginally tighter but every clause 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 13-parameter mutation with no annotations, no output schema, and 38% schema coverage, the description is thin. The routing guidance helps selection, but much of the parameter surface and all mutation/permission semantics are left to the schema or unstated.

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 38% across 13 params, so the description should compensate. It mentions title, stage, description, links, and the estimate group including estimatedValuePeriod, but says nothing about the ID fields (quoteId, companyId, contactId, ownerUserId) or their nullability semantics. It adds marginal meaning over the schema without closing 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 a specific verb (Update) and resource (DealDesk case), then enumerates the mutable field groups (title, stage, description, links, estimates including estimatedValuePeriod). It explicitly routes to the sibling dealdesk.patch_card for the desk-card path, so the agent can distinguish it from patch_card without opening either 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 clear context: 'For an existing desk card, prefer dealdesk.patch_card with the same estimate fields (it updates the linked case when one exists).' This names the alternative and the selecting condition. It lacks an explicit 'do not use when...' clause, but the routing rule is actionable enough to guide tool 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses an optimistic concurrency requirement, but does not explain permissions, what happens on revision mismatch, whether updates are partial or full, or what side effects occur. For a 10-parameter mutation, this is a significant gap.

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 short sentences with no wasted words, and it front-loads the primary action before the prerequisite. It is efficient, though its extreme brevity leaves little structure for the parameters it omits.

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 tool is a complex mutation with 10 parameters, a nested object, no annotations, and no output schema. The description only covers the concurrency prerequisite, doing little to fill the large gaps in schema coverage or explain mutation behavior. It is not adequate for correct invocation without further investigation.

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 10%, so the description must compensate. It explains the origin of expectedRevision, which is useful, but leaves companyId and the other eight parameters undocumented, including the open-ended 'fields' object. Most parameter meaning is absent.

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: 'Update a company.' This distinguishes it from siblings like get_company, list_companies, and create_company by verb. It does not clarify whether this is a partial patch or full replacement, but the core purpose is 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?

It gives a concrete prerequisite and workflow: 'Requires expectedRevision from get_company for optimistic concurrency.' This tells the agent to call get_company first. There are no explicit when-not-to-use or alternative-tool conditions, but the key context is present.

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?

With no annotations, the description carries the full burden. It does disclose two useful behaviors: deletion is unsupported and updatedAt should be fetched beforehand (implying concurrency control), which is more than most peers offer. However it omits permissions/auth requirements, whether the update is partial or full, and what happens when expectedUpdatedAt is stale.

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 action, then the prerequisite, then the hard constraint. Every sentence carries distinct information and none is wasted.

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

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

For a mutation tool with no annotations, no output schema, and 6 parameters at 17% coverage, the description is thin but not empty: it covers the sourcing workflow and the delete limitation. The unstated behavior of expectedUpdatedAt and the patch-vs-replace semantics leave an agent with real gaps before calling it.

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 17% (only projectId is documented), so the description must compensate. It references noteId and updatedAt but only as values to fetch via get_company, never explaining expectedUpdatedAt's concurrency semantics, the title/text relationship, or companyId. Most of the six parameters remain semantically opaque.

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 ('Update an existing company note'), which cleanly separates it from add_company_note and patch_contact_note/patch_card_note by resource. It is clear without opening the schema, though it doesn't explicitly contrast itself with the sibling note-patch 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?

Gives an explicit prerequisite workflow ('Prefer get_company first for noteId and updatedAt') and a boundary condition ('Delete is not available through MCP'). It tells the agent how to source required values, but stops short of naming the alternative tools (add_company_note vs patch_company_note) for the create-vs-update decision.

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?

With no annotations, the description carries the full burden but delivers only one behavioral fact: optimistic concurrency via expectedRevision. It omits what happens on revision mismatch, whether this is a partial merge or replace, and any permission requirements for a mutation 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 short sentences, front-loading the operation then the key constraint. No filler; 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?

A 9-parameter mutation tool with no annotations, no output schema, and near-zero schema coverage needs more than two sentences. Update semantics (fields merging vs replacement), failure modes, and field-level meaning are all 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 only 11% (just projectId documented) across 9 parameters. The description adds useful meaning only for expectedRevision (its source), leaving email, fields, locale, firstName/lastName, and displayName undocumented in both schema and 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?

States a clear verb+resource ('Update a contact'), which is unambiguous against siblings like create_contact and get_contact. It does not explicitly name alternatives, but 'patch/update' vs 'create'/'get' is self-evident from the name pair.

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?

Adds one workflow prerequisite: expectedRevision must be obtained from get_contact, which implies a read-then-write sequence. However it gives no when-to-use conditions versus create_contact or patch_contact_note, so guidance is only partially 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?

With no annotations, the description must carry the behavioral burden. It discloses that this is a mutation and that deletion is impossible via MCP, which is useful, but it says nothing about required permissions, whether unspecified fields are preserved (patch semantics), or how expectedUpdatedAt drives concurrency — all material for a write 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?

Three short, front-loaded sentences with no redundancy: action, prerequisite, and boundary. 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 mutation with no annotations and no output schema, the description covers the prefetch requirement and the delete limitation but omits concurrency semantics, field-preservation behavior, and most parameter meanings, leaving real gaps an agent must 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 coverage is only 17%, so the description must compensate. It references noteId and updatedAt (for expectedUpdatedAt), but leaves contactId, title, and the projectId scoping rule unexplained, and never clarifies that text is required while title is optional.

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+resource ('Update an existing contact note'), which cleanly separates it from the sibling add_contact_note (create). However, it does not name that sibling explicitly, so differentiation is implied rather than spelled out.

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 a concrete prerequisite ('Prefer get_contact first for noteId and updatedAt') and a boundary ('Delete is not available through MCP'), which tells the agent when this tool applies and what it cannot do. It stops short of explicitly routing creation to add_contact_note or contact edits to patch_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?

With no annotations, the description carries the full burden. It usefully discloses that only draft-stage status is accepted and that pricing lines are untouched, which is real behavioral content. But it says nothing about permission requirements, whether updates are reversible, or how omitted fields behave, leaving major gaps for a mutation 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 tight sentences, no redundant restatement of the tool name or schema, with the scope statement front-loaded and the exclusions immediately after. Every clause 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 an 11-parameter mutation with no output schema and very low schema coverage, the description covers the core intent but omits the project-scoping/auth story and the snapshot semantics that an agent must understand to call this 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 18% across 11 parameters. The description names title, language, currency, customer snapshots, and experience template, adding meaning for roughly half the surface, but opportunityId, projectId scoping, and the three distinct snapshot objects remain unclarified.

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 (Update) and resource (draft quote metadata) with an enumerated field list, and explicitly carves out what it is not (no accept/decline, no pricing-line replacement). That boundary work lets an agent separate it from replace_quote_items and clone_quote 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?

The two negative clauses ('Does not accept/decline', 'does not replace pricing lines') function as clear when-not guidance, routing pricing edits to replace_quote_items and status transitions elsewhere. It stops short of naming the alternative tools or stating prerequisites (e.g. quote must be in draft).

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the non-obvious 'close without deleting' effect of isOpen=false, which is real value beyond the schema, but it omits permissions/auth needs, what happens to unrelated fields, and whether updates are reversible.

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, front-loaded with the operation and then the key field behavior. No filler; every clause 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 mutation tool with no annotations, no output schema, and only 43% param coverage, the description is adequate but leaves gaps: it never explains the projectId authorization model or the identifier requirements, both of which 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 description coverage is 43% (below 50%), so the description must compensate. It names four of seven fields (label, password, quickchat, isOpen), mapping 'quickchat' to quickchatEnabled, but adds nothing for projectId or quoteId/shareId, and the important multi-project projectId semantics appear only in the schema.

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

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

States a specific verb (Update) and resource (quote share link) plus the four mutable fields, which distinguishes it from create_quote_share and list_quote_shares by name resemblance. It does not explicitly name those siblings, but the 'patch/update' framing 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?

'Set isOpen=false to close the link without deleting' is genuine when/how guidance for one field, implying this tool is preferred over deletion for closing a link. However, there is no guidance on when to use this versus create_quote_share or other share operations, so usage is only partially covered.

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?

With no annotations, the description carries the full burden and does add real behavioral context: the authorship/staff permission model for comments, touchpoints and tasks, plus a pointer to the optimistic-concurrency token. It does not explain patch semantics (that omitted fields are left unchanged) or what happens on a stale updatedAt conflict, so gaps remain.

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 with the core action front-loaded and no filler. Efficient, though it could be organized slightly better to separate the scope statement from the permission and workflow guidance.

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 19-parameter mutation tool with no annotations and no output schema, the description gives scope, auth and a pre-step but leaves patch semantics, conflict behavior and most parameter meanings unstated. Adequate to attempt the call, not enough to call it confidently in edge cases.

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

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

Schema description coverage is only 42% across 19 parameters, so the description should compensate more than it does. It groups parameters into three meaningful domains (comment, task, touchpoint), which helps, but many undocumented fields (note, dueAt, subject, contactIds, occurredAt, recurrence, participants, assigneeUserId, touchpointType, mentionedUserIds) get no explanation in either place.

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 ('Update an existing status update') and usefully enumerates the three sub-kinds of update (comment body, task fields/status, touchpoint fields), which distinguishes it from create_status_update and list_status_updates. It never names a sibling tool by name, so sibling differentiation is implicit rather than explicit.

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

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

Gives a concrete workflow ('Prefer list_status_updates first for statusUpdateId and updatedAt') and states the authorization rule that selects who may edit what. No explicit when-not-to-use guidance or comparison against patch_card_note / patch_case, so it stops short of full routing 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?

With no annotations provided, the description carries the full behavioral burden, yet it only discloses one trait: the call is side-effect free. It says nothing about auth requirements, how invalid configurations are reported, or whether results are cached, which leaves meaningful gaps for an evaluation 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?

A single compact sentence with the key constraint "(side-effect free)" placed up front and no wasted words. It is efficient, though its brevity contributes to the under-specification noted elsewhere.

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

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

For a tool with a required nested object, no output schema, and no annotations, the description is too thin. It never explains the expected configuration structure or what the evaluation returns, so an agent lacks what it needs to call this 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 50%: projectId and revisionId carry descriptions, but the required "configuration" (a nested object) and "locale" are undocumented in both schema and description. The description adds no parameter meaning, most critically for the required nested configuration whose shape an agent must know.

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 gives a specific verb ("Evaluate") and resource ("a CPQ configuration against the Portfolio"), so an agent can identify the operation. However, it does not differentiate itself from the sibling dealdesk.portfolio_summary or explain what "Portfolio" means in this context, leaving some 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?

There is no indication of when to use this tool versus alternatives like portfolio_summary, create_quote_from_configuration, or render_quote_totals. No prerequisites, preconditions, or exclusions are stated beyond the terse "(side-effect free)".

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?

With no annotations, the description carries the full behavioral burden. 'Get' implies a read, but there is no disclosure of auth requirements, rate limits, what distinguishes draft from published results, or whether the summary is computed or cached — significant gaps for a tool with zero annotation coverage.

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 short sentence with no filler, and the resource is front-loaded after the verb. However, the brevity veers into under-specification rather than genuine conciseness, so it earns only a middling score.

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?

No output schema, no annotations, and one of two parameters undocumented in both schema and description. For a summary-retrieval tool the description should at minimum explain what is returned and how draft vs published differs; it does not.

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%: projectId is well documented in the schema, but locale has no description anywhere. The description adds nothing beyond the schema — no locale format, no explanation of the draft/published toggle that a caller would need to interpret results. It fails to compensate for the uncovered parameter.

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 verb 'Get' and a resource 'Portfolio draft/published summary for a project', which is more than a tautology. However, it never clarifies what a 'draft/published summary' actually contains, and it does not distinguish itself from the sibling dealdesk.portfolio_evaluate, leaving ambiguity about 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?

No indication of when to call this instead of portfolio_evaluate or the various get_*_summary siblings. There are no prerequisites, exclusions, or contextual triggers mentioned anywhere in the description.

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?

With no annotations, the description carries the full burden and does disclose an important trait: it only renders in MCP Apps hosts (ChatGPT), implying environment dependency. However, it omits permissions needed, whether it mutates anything, and behavior in hosts that don't support widgets.

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 action and the routing rule. No filler; every sentence carries a distinct fact.

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?

An output schema exists, so return values need not be explained, and the description covers the key host constraint and sibling routing. It is nearly complete for this tool, missing only parameter-level and host-failure guidance.

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%, and the description says nothing about cardId or projectId. The undocumented cardId is required, so the description fails to compensate for the coverage gap, leaving projectId's auth-conditional behavior documented only in the schema.

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

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

States a specific verb and resource: show the DealDesk card-summary widget. It also explicitly distinguishes itself from the sibling get_card, noting that data tools return JSON only, so an agent can route correctly 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?

Gives a clear condition: 'Call this when the user should see the card UI,' and contrasts it with data-returning tools like get_card. It lacks explicit when-not guidance (e.g., non-UI hosts where it can't render), but the use context 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?

No annotations are provided, so the description must carry behavioral disclosure. It usefully states that the PDF is written to the exports folder, returns a file path, and is not persisted on the quote. However, it omits auth requirements, whether existing files are overwritten, error behavior, and idempotency.

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, front-loaded with the action and output, followed by the key persistence caveat. No filler or redundant statements.

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 straightforward render tool with no output schema and no annotations, the description covers output path, return value, and persistence behavior. It leaves usage routing and some edge-case behavior to inference, but the schema handles parameter guidance, so it is nearly 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 description coverage is 67%, with projectId and selectedOptionIds described in the schema. The description adds no parameter-level details beyond implying the project context; quoteId has no description in either place. A baseline 3 is appropriate given moderate 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?

States a specific verb (Generate) and resource (quote PDF), plus the output location (project DealDesk exports folder) and return value (file path). This clearly distinguishes it from siblings like render_quote_totals, which produces totals rather than a PDF.

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 on when to use this tool versus alternatives such as render_quote_totals or get_quote_summary. The purpose implies usage, but there are no conditions, prerequisites, or 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?

With no annotations, the description carries the burden and does disclose key traits: it renders a UI widget, it requires an MCP Apps host (ChatGPT), and it is distinct from JSON-returning get_quote. It stops short of stating side effects, auth needs, or failure behavior, but the render-vs-data distinction is genuinely useful.

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, front-loaded sentences with zero filler; the host requirement and trigger condition lead, and the get_quote contrast closes efficiently.

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?

An output schema exists, so return values needn't be described, and the description covers host constraints and usage context. The only real gap is the undocumented required quoteId, which leaves the definition slightly short for a 2-parameter 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 only 50%: projectId is documented in the schema while the required quoteId has no description anywhere. The description adds no parameter meaning at all, so it fails to compensate for the undocumented required parameter.

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+resource ('Show the DealDesk quote-totals widget') and explicitly distinguishes itself from get_quote by noting get_quote returns JSON only. It does not, however, differentiate from the nearby sibling get_quote_summary, which also concerns quote totals.

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 when the user should see quote totals UI' gives a clear triggering condition, and the get_quote contrast implicitly routes data-only needs elsewhere. No explicit when-not guidance or named alternatives beyond that one contrast.

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?

With no annotations, the description carries the full burden and does meaningful work: it discloses that this is a destructive full-array replacement (existing lineItems/options/groups are overwritten), that it is draft-only, and that the server refuses accepted/declined quotes. It omits auth/permission requirements and any atomicity or partial-failure behavior, keeping it short of 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?

Two tight sentences with the core action front-loaded, then the gating constraint, then the payload rule. Every clause carries information and there is no filler.

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

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

An output schema exists, so return values need no explanation. For a six-parameter mutation with no annotations, the description covers the essential behavior (replacement, draft-only, full arrays) but leaves the sibling relationship and CPQ priceConfirmations context unaddressed.

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 33%. The description names three of the six parameters (lineItems, options, groups) and reinforces that full arrays must be sent, which adds replacement semantics. But it says nothing about quoteId, projectId, or priceConfirmations, and gives no shape guidance for the array items, 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?

The description states a specific verb (Replace) and resource (draft quote lineItems, options, and groups), and the 'Send the full arrays you want persisted' phrasing signals full-replacement semantics that distinguish it from patch_quote. It does not explicitly name the sibling it supersedes, so an agent must infer the boundary with patch_quote/update_quote_from_configuration.

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 a clear negative condition — 'Draft-only; refused for accepted/declined quotes' — so the agent knows when the call will fail. However, it never names an alternative tool for accepted/declined quotes or explains when to prefer this over patch_quote, leaving the routing decision partly to 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?

With no annotations, the description carries the full burden and does disclose the key mutation semantics: a 'full commercial replace' (destructive to existing commercial content) while preserving title/customer/ownership, plus the optional quoteLayout reshaping presentation. It omits auth/permission requirements and reversibility, so it stops short of full coverage.

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 with the operation and its destructive scope front-loaded, then the preservation guarantee, then the optional presentation parameter. No filler and nothing buried.

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