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 clarifies note shape (title + body) and routing, but does not say whether notes are append-only versus replaceable, whether cardId/projectId must exist and be authorized, or what the call returns. The existence of a sibling patch_card_note implies add is additive, but the description never states 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?

Two tight sentences plus one routing clause, front-loaded with the positive action before the exclusions. Every clause either defines the tool or routes to an alternative; 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?

For a 4-parameter, unannotated mutation tool with no output schema, the description covers selection and routing well. The remaining gap is behavioral: no statement of note persistence semantics, ordering, or auth requirements, which an agent calling a write endpoint would benefit from.

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 adds only the 'title + body' framing, which maps to the already-documented text and title parameters. It adds no meaning for cardId (undocumented in the schema) or for the optional/required nature of title beyond what the schema already declares. Baseline 3 when the schema does most of the work.

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 (title + body) to a desk card. It also distinguishes itself from dealdesk.patch_card by explicitly reserving the card description field for that sibling, so an agent can tell the two apart 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 explicit when-not-to-use routing: use patch_card with description for the main card description, and use log_email (or create_status_update with email_incoming/email_outgoing touchpoints) instead of notes for logging emails. This is exactly the exclusion guidance that prevents sibling misselection.

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 discloses only that the note is 'structured' with title + body; it says nothing about whether this is a mutation, required permissions, whether notes are editable/deletable later (patch_company_note exists), or any side effects. For an unannotated write tool 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?

A single tight sentence with the resource and scope front-loaded and no filler. It is efficient, though its brevity is partly the source of the missing behavioral detail rather than a virtue in itself.

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-param mutation tool with no annotations and no output schema, the description is minimally adequate: it conveys what is created and on which entity. It omits any behavioral, permission, or lifecycle context that would let an agent call it confidently, leaving the definition thin overall.

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%, so most parameters are already documented in the schema. The description adds only marginal value by tying 'title + body' to the title/text parameters, and it does nothing to clarify the undocumented companyId or the projectId/project-must-match-key constraint beyond what the schema already states.

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

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

States a specific verb (add) and resource (structured note) plus the target entity (customer-directory company) and the two fields involved (title + body). Naming the company scope implicitly separates it from the add_card_note and add_contact_note siblings, though it never names them 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?

The description gives no when-to-use condition, no prerequisites, and no alternatives. An agent must infer from the tool name alone that this is the company variant rather than the card/contact note sibling, and there is no guidance on when a company note is appropriate versus a contact or card note.

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 required permissions, whether notes are visible to customers, editability, or what the response contains. For a write operation 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 efficient sentence with the entity and payload shape front-loaded; nothing is wasted. It is arguably too terse for a mutation tool, but structurally it is clean.

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 a mutation against a shared contact directory, the description should state at least permissions or visibility expectations. Against this complexity and the 30-plus sibling tools, the single sentence is not sufficient.

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

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

Schema description coverage is 75%, and the schema already documents text, title, and projectId. The description's '(title + body)' merely restates the title/text fields without adding format, length, or content-type guidance, so it lands at the baseline for a well-covered 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 ('Add') and resource ('note') scoped to a 'customer-directory contact', and the '(title + body)' parenthetical signals the structured shape. It implicitly distinguishes itself from the sibling add_card_note/add_company_note by naming the contact entity, though it 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?

The description gives no when-to-use guidance and never mentions the obvious alternative patch_contact_note, which a sibling tool. An agent must infer whether to add a new note or patch an existing one from the tool names alone.

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 discloses only that the result is a new draft; it never says whether the source quote is left untouched, whether line items/shares are copied, what state the draft lands in, or what permissions are required beyond the schema note on projectId.

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-loaded with the core action and with no filler. The trailing 'Prefer clone...' sentence is colloquial but earns its place as routing 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?

An output schema exists so return values need not be described, and required/optional params are clear from the schema. For an unannotated mutation tool with a nested customerReference object, however, the description should say more about side effects and what gets copied vs. retargeted.

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 low (29%, 7 params), so the description must compensate, and it partially does by naming the retargetable fields (title, opportunity, Customer Directory company/contact). But customerReference, opportunityId, and the relationship between companyId/contactId and customerReference are left unexplained.

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 ('Clone an existing quote into a new draft') that an agent can distinguish from create_quote, create_quote_from_configuration, and patch_quote among the siblings. The output being a draft, not a finalized quote, sharpens the intent further.

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 selection heuristic: 'Prefer clone when the user likes a past quote.' That routes the agent away from create_quote in a common scenario, though it never names the alternative tools or states when cloning is inappropriate.

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 only implies mutation via 'Create'. It says nothing about permission requirements, whether the projectId must match the API key/OAuth project (buried in the schema), idempotency, or failure modes.

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 efficient, though the terse parenthetical sacrifices some explanatory detail.

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 described. However, for a mutation tool with zero annotation coverage, the description is thin on behavioral and usage context needed to invoke it correctly.

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

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

Schema coverage is 75%, so the schema already documents most parameters. The description highlights title, stage, description, and company/contact but omits notes (deprecated alias), deskDescription, and the critical projectId scoping constraint, adding only marginal value over 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 ('Create') and resource ('desk card') and enumerates the salient fields in the parenthetical. It is clearly separable from siblings like get_card, patch_card, and list_cards, though it does not explicitly distinguish itself from create_case or create_quote.

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, prerequisites, or named alternatives are given. The agent must infer usage context entirely from the verb and the sibling list.

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, yet it discloses nothing about the mutation: no permission requirements, no idempotency or duplicate-handling behavior, no note on which fields are set at creation versus updated later via patch_case, and no return behavior. The single parenthetical about case semantics is the only added context.

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

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

A single front-loaded sentence with no filler, and the most important disambiguation (case, not opportunity) comes first. It is efficient, though the space used is spent on a distinction of limited value relative to the missing parameter and usage 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 mutation tool with 11 parameters, no annotations, and no output schema, one sentence is far too thin. An agent gets no coverage of required-vs-optional fields, no post-creation behavior, and no routing guidance among the sibling creation tools.

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

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

Schema description coverage is 9% (only projectId is documented), so the description should compensate but adds nothing about any of the 11 parameters — not even that projectId must match the API key/OAuth project, or that the other fields are optional. Field names are largely self-describing, which prevents a 1, but no meaning is added beyond the schema.

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

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

States a specific verb and resource ('Create a DealDesk case') and adds a clarifying parenthetical about what a case is. However, the negative disambiguation targets a 'Salesforce Opportunity search', which is not among the listed siblings; it never distinguishes create_case from create_card, create_quote, or create_contact, which are the actual confusable write 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?

There is no statement of when to create a case versus the many other creation tools in the sibling set (create_card, create_quote, create_company, create_contact, create_status_update). No preconditions, no exclusions, no alternative routing. The parenthetical only clarifies vocabulary, not usage.

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 behavioral disclosure, and it does add genuine value: externalId is auto-generated as local-company-<uuid> when omitted, and the caller is told not to require fields.externalId. However it says nothing about permissions, conflict/duplicate handling, or mutation side effects.

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

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

Three short clauses, front-loaded with the core action, then the field-placement rule, then the externalId caveat. Efficient, though the second and third clauses are really parameter notes rather than the core purpose.

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

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

For a 10-parameter creation tool with nested fields, no annotations, and no output schema, the description covers only a fraction of what an agent needs. It should address required-field expectations, what the response contains (e.g., the created id), and duplicate/conflict 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 coverage is only 60%, but the description compensates meaningfully: it explains the name-to-legalName alias, the top-level versus fields placement, and the auto-generation of externalId. The remaining gap is the undocumented params (taxId, locale, emailDomains, registrationId) that neither source explains.

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 company in the customer directory.' An agent can distinguish this from patch_company/get_company by the create verb, but the description never explicitly names those siblings or contrasts 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?

It gives usable guidance on how to call the tool (send legalName or name at the top level) but no guidance on when to use it versus alternatives like create_contact or the various patch tools. Usage is implied by the create verb 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 full burden, and it does disclose one real behavioral trait: externalId is auto-generated when omitted. It says nothing about permissions, duplicate handling, idempotency, or what the call returns, leaving significant 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 with the core action front-loaded and the constraint following immediately. No filler, nothing repeated from the title or schema.

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

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

For a 9-parameter mutation tool with no annotations and no output schema, the description covers identity and externalId but omits permissions, project-scoping behavior, and return shape. It is adequate but not sufficient on its own.

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 compensates by clarifying the conditional identity requirement (displayName OR name OR firstName/lastName) and externalId's optionality/auto-generation — a relationship the schema, which lists only projectId as required, does not express. Email, fields, and locale remain undocumented.

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

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

States a specific verb and resource ('Create a contact in the customer directory'), which cleanly separates it from siblings like create_company or create_card. It stops short of naming any alternative, but the resource is unambiguous.

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

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

The description gives no when-to-use guidance or routing to alternatives; it never says when this is preferable to other create_* tools or what context is needed. The 'requires displayName or name...' clause is a field requirement, not usage guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that this yields a 'draft' and that snapshots are resolved server-side when directory ids are supplied, but omits permissions/auth requirements, mutation side effects, and idempotency for a create operation.

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

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

Three compact sentences, front-loaded with the core action, then the id-preference rule, then the sibling routing. Every sentence carries distinct, non-redundant 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?

An output schema exists, so return values needn't be explained, and the description covers creation semantics, key parameters, and the sibling alternative. The only gap is behavioral detail (auth, side effects) that goes unaddressed in the absence of annotations.

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 64%, so roughly four parameters (currency, language, opportunityId, etc.) are thin. The description adds genuine meaning beyond the schema by explaining why companyId/contactId are preferred (server-side snapshot resolution) and loosely mapping lineItems/options/groups, but it doesn't compensate for the uncovered parameters.

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

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

States a specific verb+resource ('Create a classic draft quote') and enumerates the optional components (lineItems, options, groups). It explicitly distinguishes itself from the sibling create_quote_from_configuration ('use ... for CPQ'), so an agent can 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 explicit when-to-use ('for free-form / open positions') and a named alternative ('use create_quote_from_configuration for CPQ'), plus a preference rule for companyId/contactId. The routing condition that selects this tool versus its sibling is fully 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 full burden; it does add real value by noting quoteLayout is presentation-only and that 'commercial amounts stay server-evaluated', telling the agent pricing is not client-supplied. It still omits auth/permission needs, reversibility, and what happens to unspecified fields, so a mutation tool at this complexity is under-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?

Two dense sentences with no filler, front-loading the primary action before the quoteLayout caveat. Efficient, though the parenthetical '(CPQ)' and the semicolon clause make it slightly compressed for a high-stakes create operation.

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 a 12-parameter, nested-object, no-annotation mutation tool requires more than two sentences. Nothing explains the CPQ configuration contract, how the revision IDs interlock, or who may call it, leaving meaningful 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 description coverage is only 25% across 12 parameters, so the description is expected to compensate and does not. It clarifies quoteLayout and hints at configuration semantics ('server-evaluated amounts') but leaves title, locale, currency, language, companyId, contactId, customerReference, and both revision IDs undescribed.

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 quote from a published Portfolio configuration (CPQ)') and the CPQ provenance implicitly separates it from sibling create_quote. It never names those siblings, so an agent must infer the distinction, keeping it below 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 'from a published Portfolio configuration' implies the precondition (a published config must exist), which is useful implied usage guidance. But there is no explicit when-to-use versus create_quote, update_quote_from_configuration, or clone_quote, and no 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?

No annotations are provided, so the description carries the full burden. It helpfully discloses the two return paths and the lifecycle constraint (soft-close only, no delete), but says nothing about authorization requirements, whether password protection changes behavior, or idempotency/re-creating an existing share.

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 core action and followed by the lifecycle constraints. Every clause earns its place 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?

With no output schema, the description correctly names the two return values, but three of five parameters remain undocumented in both schema and description, and no auth or uniqueness behavior is given. Adequate for a create tool but with real 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 only 40% – label, quickchatEnabled and password have no schema descriptions – and the tool description adds no parameter meaning at all (it never mentions any of the five inputs). With low coverage the description is expected to compensate, and it does not.

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

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

States a specific verb and resource ('Create a customer share link for a quote') that an agent can immediately act on, and explicitly distinguishes itself from the sibling patch_quote_share used for the opposite lifecycle step. The return fields named (classicPath, experiencePath) further pin down what 'share link' means here.

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

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

Gives clear context: use this to create a share, then soft-close later with patch_quote_share isOpen=false, and delete is unavailable via MCP. It routes to the alternative for teardown but does not state when this tool should NOT be used (e.g., if a share already exists).

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 discloses very little: no statement about permissions, whether mentionedUserIds produce notifications, whether the projectId must match the auth context, or that recurrence applies only to tasks. 'Create' implies mutation, but nothing about side effects or reversibility is given.

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 front-loaded sentences with no filler. The primary action and its variants come first, and the routing hint is appended second. Nothing redundant.

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 is thin. It never explains the type-dependent required-field matrix (body for comment, title for task, touchpointType for touchpoint), the entityId/cardId alias, or what the call returns or triggers.

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 74%, so most parameters are self-documented. The description usefully frames the parameters into three type modes and restates the touchpoint subtype enum, but adds no syntax, format, or interaction detail (e.g., cardId vs entityId aliasing, which fields each mode requires) beyond what the schema already says.

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 status update') and enumerates the three mode variants (comment, task, touchpoint) with the touchpoint subtypes. It only partially differentiates from siblings, naming log_email but not the adjacent note tools (add_card_note, add_company_note), so an agent still has to infer the boundary with those.

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 with an alternative: 'Prefer dealdesk.log_email for inbound/outbound email logs.' That is a real when-to-use-this-vs-that statement. It lacks a when-not clause for the note-writing siblings and doesn't say when to pick comment vs task vs touchpoint.

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 the important non-obvious trait that this call unlocks skill-gated tools, which is real behavioral value beyond the name. It does not say whether the unlock persists across sessions, what permissions are required, or that projectId must match the API key's project.

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 no filler, front-loading the listing behavior before the unlock mode. Slightly dense for two distinct behaviors but nothing 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 two-parameter meta-tool with no output schema and no annotations, the description covers both invocation modes adequately. It leaves open what the returned domain/tool list looks like and what 'skill-gated' entails, which is where an agent would most likely stumble.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates only six of the eight enum values (omitting portfolio-authoring and export), which is a minor mismatch, but it does usefully convey that domain is optional and that omission lists domains only.

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

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

The description states a concrete verb and resource: listing DealDesk tool domains, with a secondary mode that unlocks skill-gated tools for one domain. It is distinguishable from CRUD siblings, but it does not explicitly differentiate itself from dealdesk.list_skills, which sounds closely related, and the word 'additional' is left unexplained.

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 modes are implied (list domains vs. unlock a domain), and the schema's 'Omit to list domains only' clarifies the branch. However, there is no statement of when an agent needs discovery at all, no sequencing guidance relative to list_skills, and no mention of prerequisites beyond projectId.

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 adds little: 'Bounded export path' gestures at a limit without explaining it. It doesn't state permissions, whether the export is synchronous, size/time limits, or how results are delivered.

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-loaded with the core purpose. However, the trailing 'Bounded export path' is vague filler that doesn't earn 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 export tool with no annotations, no output schema, and partially documented params, the description is too thin. It omits what the file contains, how it's returned, and the constraints implied by 'bounded'.

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

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

Schema coverage is 67%; two enum params (view, source) are only partially described and 'source' has no schema description at all. The description adds no parameter meaning and doesn't compensate for the gaps.

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) plus the output format (Excel). An agent can distinguish it from the many list/get/create siblings, though it doesn't name any sibling or explain scope boundaries.

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?

Only 'for analysis' hints at a use case, and 'Bounded export path' is opaque. There is no statement of when to use this vs. the render_*/get_* siblings, no prerequisites, and no 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?

No annotations are provided, so the description carries the full behavioral burden and does almost nothing with it. It does not state that this is a read-only lookup, what happens if the id is unknown, or any permission/project scoping requirement, despite projectId being constrained to the API key's project. Only the bare 'get' verb implies safe retrieval.

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

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

One short, front-loaded sentence with no filler or repetition. It is efficient, though the terseness contributes to the missing usage and behavioral detail 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?

An output schema exists, so return values need not be described. For a simple two-param read that is the main saving grace, but with zero annotations and half the parameters undocumented, the definition leaves the agent guessing on project scoping and error 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 coverage is 50%: projectId is well documented in the schema, while cardId is undocumented anywhere except the description's 'by id'. The description confirms an id-keyed lookup but adds no format or source guidance (e.g. where card ids come from) beyond what the schema already conveys.

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?

Clear verb+resource+scope: 'Get one desk card by id' states a single-resource retrieval keyed by id. It implicitly distinguishes itself from list_cards (plural/browse) and patch_card/create_card, though it never names those siblings explicitly. An agent can determine what the tool does without opening 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?

No when-to-use or when-not-to-use guidance is given. There is no mention of how this differs from get_company, get_quote, or list_cards, nor any prerequisite or context (e.g. 'use when you already have a card id'). A single narrow read tool is low-risk, but the description offers no routing help.

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 delivers almost nothing beyond the word 'Get'. It implies a read-only retrieval but says nothing about return shape, error behavior for missing ids, or authorization constraints (the projectId/API-key matching rule lives only 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?

A single short sentence with no filler and the key scoping detail ('one case by id') front-loaded. It is efficient, though arguably under-specified rather than optimally concise.

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-required-parameter lookup with no annotations and no output schema, the description omits the return shape, id sourcing, and failure modes. The simplicity of the operation softens this, but the definition is not complete enough to call confidently.

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 caseId has no description anywhere. The description's phrase 'by id' faintly maps to caseId but adds no format, namespace, or sourcing detail that would 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?

States a specific verb (Get) and resource (DealDesk case) scoped to a single record by id, which is clearer than a bare name restatement. However, it does not differentiate itself from sibling single-record getters like dealdesk.get_card or dealdesk.get_quote beyond the resource noun.

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

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

No when-to-use guidance is given. It does not say to prefer this over dealdesk.list_cases for fetching a known case, nor does it mention any prerequisites for obtaining a caseId. 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?

No annotations are provided, so the description carries the full behavioral burden and delivers almost nothing beyond 'Get'. It does not state what happens when the company is not found, whether it is a safe read (though the verb implies it), what scope/permission is needed, or what the response looks like. The projectId scoping caveat lives only 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 short sentence, front-loaded with the verb and resource, with no wasted words. Its brevity is a virtue structurally, though it edges toward 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 two-required-parameter tool with no annotations and no output schema, this description is too thin: it never addresses the projectId scoping requirement or the not-found/error behavior. Because there is no output schema, the description arguably owes the reader a hint about what a company record contains, and it offers none.

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 companyId has no description there. The description only says lookup is 'by id', which merely confirms companyId's role and adds no format, source, or constraint detail. It does not compensate for the companyId documentation gap.

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

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

The description states a specific verb and resource ('Get a company') and narrows it to a single-entity lookup 'by id', which distinguishes it from a listing sibling like list_companies. It does not, however, distinguish it from lookalikes such as get_company_commercial_summary or add_company_note, 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?

There is no guidance on when to use this tool versus alternatives such as list_companies, discover, or get_company_commercial_summary. The only implied usage cue is 'by id', which an agent must infer from the parameter name on its own.

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 (open/won/lost breakdown) but says nothing about auth/project scoping requirements, time window or stage definitions, pagination, or how linked records are counted — all substantive gaps for a summary endpoint.

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 resource and the return contents front-loaded; no filler or redundancy. It is perhaps terse to the point of under-specification, but structurally 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?

With no annotations, no output schema and one of two parameters undocumented, the description would need to fill more of the gaps. It names what is returned but omits time range, currency/aggregation basis, and access constraints an agent needs before 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 50%: projectId is described in the schema as needing to match the API key/OAuth project, but companyId has no description anywhere. The description adds no parameter-level meaning, so 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 specific verb+resource ('get_company_commercial_summary' for a company) and enumerates the returned content: open/won/lost pipeline value plus linked deals, quotes and orders. It is distinguishable from the sibling get_contact_commercial_summary by scope, though it doesn't name that sibling or otherwise route 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?

There is no indication of when to use this tool versus get_company, portfolio_summary, get_quote_summary or the contact variant. The purpose is implied by the name and one-line description, but no conditions, prerequisites or alternatives are given.

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

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

No annotations are provided, so the description carries the full burden. 'Get' implies a read, but it does not disclose auth requirements, behavior when the id is missing, or anything about the response shape.

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 states verb, resource, scope, and lookup key with no wasted words.

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

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

For a simple single-item read with two required params and no output schema, the description is minimally adequate. Given the absence of annotations, it leaves the behavioral profile (auth, not-found handling) entirely unspecified.

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, contactId is not). The description's 'by id' loosely maps to contactId but adds no format or constraint detail, so it does not compensate for the undocumented 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?

Specific verb+resource+scope ('Get one ... contact by id'), which contrasts with the sibling list_contacts and other get_* tools. It does not explicitly name a sibling to differentiate from, so it falls 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?

There is no statement of when to use this versus list_contacts, get_contact_commercial_summary, or other contact-related siblings. The agent must infer usage purely from the verb 'Get'.

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 disclose what the operation returns (pipeline value buckets and linked deals/quotes/orders), which is useful content context. It says nothing about permissions/auth, read-only nature, or the projectId-must-match-key constraint that is only implied by the schema. Adequate 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?

A single front-loaded sentence listing the returned value tiers and linked entities, with zero filler. Nothing 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?

Because there is no output schema, the description usefully enumerates return contents, which is the main gap it needed to fill. But for a tool that duplicates a company-level sibling, it lacks routing guidance and fully omits any detail on the undocumented contactId 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 50%: projectId is documented in the schema, but contactId has no description anywhere. The description mentions 'for a contact' but adds no syntax, format, or sourcing detail for either parameter, so it 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?

States a specific verb+resource ('get_contact_commercial_summary' for a contact) and enumerates what it returns: open/won/lost pipeline value plus linked deals, quotes, and orders. That is clear and differentiated from plain 'get_contact'. However, it never distinguishes itself from the near-identical sibling 'get_company_commercial_summary', so the agent must infer the contact/company split from the name alone.

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 or when-not-to-use guidance is provided, and no alternative is named. The agent gets no signal on when to prefer this over 'get_contact' or 'get_company_commercial_summary'. Usage is left entirely to inference 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 burden. It implies a read but never states read-only behavior, pagination, or that projectId must match the API key/OAuth project (only the schema mentions that). It reads as a list of return fields rather than behavioral disclosure.

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 about 'classic + rich/experience paths' is the only slightly opaque element.

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's enumeration is largely redundant with that. What is genuinely missing is disambiguation from sibling read/summary/render tools and any behavioral context for an unannotated 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?

Two parameters with only 50% schema coverage: projectId is documented, quoteId is not. The description adds nothing about the semantics of quoteId (format, source, scope), so it 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?

Specific verb (get) plus resource (quote) and an enumeration of what it returns: status, totals, acceptance summary, analytics, share links. However, it never distinguishes itself from close siblings like dealdesk.get_quote_summary or dealdesk.render_quote_totals, whose scope appears to overlap with 'status, totals, acceptance summary'.

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 alternatives. With siblings this similar (get_quote_summary, list_quote_shares), the agent is left to guess which tool answers which question.

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. It usefully discloses that this is a plain read of already-persisted data with no enrichment or repricing, which signals a raw, side-effect-free operation, but it says nothing about auth requirements (beyond the projectId hint), pagination, or whether the persisted view can be 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?

A single tight sentence with the scope and the key disambiguating qualifier front-loaded. No filler, though its brevity is part of what leaves the parameter gaps unaddressed.

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

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

For a simple two-parameter read tool with an output schema already covering return values, the description is adequate on scope. However, it leaves quoteId undocumented and gives no sibling routing, which for a tool sitting next to get_quote and list_quotes is 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 only 50%: projectId is documented as needing to match the API key/OAuth project, while quoteId has no description at all. The description adds no parameter-level detail to compensate for the undocumented quoteId, so it fails to close 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 (Read) and resource (persisted quote line items/options/groups and status), with a useful qualifier that the data is not enriched or repriced. It is clear what the tool does but does not explicitly differentiate itself from the closest sibling, get_quote, or from render_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?

The phrase 'without enrichment or repricing' implies the tool should be chosen when raw persisted quote data is wanted rather than a computed/rendered view, but no alternative tool is named and there is no explicit when-to-use or when-not-to-use statement. Usage is implied rather than directed.

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 never states that this is a read-only operation, how results are ordered, whether pagination exists, or how the limit default of 25 interacts with result counts.

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 well-formed sentence with the resource and filters front-loaded and no filler. Its brevity is efficient, though it borders on under-specification for a 4-parameter tool.

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 should explain read-only semantics, filtering behavior, and result shape; it explains none of these. One parameter (stage) is undocumented in both schema and description, leaving 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 coverage is 75% (q, limit, and projectId documented; stage is not), so the baseline is 3. The description adds only a light restatement that stage and search filtering exist, without explaining accepted stage values or that projectId must match the credential's project.

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

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

States a specific verb (List) and resource (DealDesk desk cards), which cleanly separates it from dealdesk.get_card, create_card, and patch_card. It does not, however, distinguish itself from other list siblings such as list_cases or list_companies beyond the noun.

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?

'with optional stage/search filters' hints at capabilities but gives no when-to-use guidance, no prerequisites, and never names an alternative (e.g., use get_card for a single card). The agent must infer usage entirely.

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. 'List' implies a read operation, but nothing is said about pagination (limit maxes at 100), default page size, ordering, or result shape, which matters for a filterable list endpoint.

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, front-loaded with the verb and resource. It is efficient with no wasted words, though the extreme brevity is under-specification rather than true 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 6-parameter, filter-driven list tool with no annotations, no output schema, and 17% schema coverage, the description is well short of complete. It leaves filter semantics, pagination, and return shape entirely undocumented.

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 very low (17% – only projectId is documented). The phrase 'optional filters' hints that q/type/stage/ownerUserId filter results, but the description never maps any parameter to a meaning, adds no syntax or allowed values, and says nothing about limit.

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

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

States a specific verb (List) and resource (DealDesk cases), so an agent knows what the tool returns. However, it offers no differentiation from the many sibling list tools (list_cards, list_quotes, list_skills) beyond the resource noun itself.

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

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

The description gives no guidance on when to use this versus alternatives like get_case or list_cards, no prerequisites beyond the projectId requirement, and no exclusions. Usage is only inferable 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. It does not say whether results are paginated, what ordering applies, whether the search is fuzzy or exact, or what authentication scope is needed beyond the schema's projectId note. For a read tool with zero annotation coverage this is a meaningful 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 front-loaded sentence with no waste. It is appropriately sized for the tool, though the brevity borders on under-specification rather than true 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?

With no output schema, no annotations, and only one of three parameters documented, the description should carry much more. It omits return shape, pagination, search behavior, and sibling differentiation, so an agent cannot invoke it confidently without guessing.

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

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

Schema description coverage is only 33% (projectId only), so the description must compensate and does not. The 'q' and 'limit' parameters receive no explanation of matching semantics or default/max behavior beyond the schema's numeric bounds.

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?

It names a specific resource (companies) and two verbs (search/list), so the agent knows the general operation. However, 'customer-directory companies' is the only scope qualifier, and it does nothing to distinguish this from siblings like dealdesk.get_company, dealdesk.discover, or dealdesk.list_contacts that operate on the same domain.

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 statement of when to use this tool versus get_company, discover, or any other list/search sibling. The 'Search or list' phrasing implies two modes without explaining what triggers which, leaving routing entirely 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?

No annotations are supplied, so the description carries the full behavioral burden, and it discloses almost nothing. It does not state return format, whether results are paginated, whether the limit caps the listing, or what permissions/project scope are required.

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 or redundancy. It is efficient, though the terseness reflects under-specification rather than deliberate brevity.

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 listing tool with no annotations, no output schema, and only 33% schema coverage, one sentence is not sufficient. It omits pagination, result shape, sorting, and how limit and q interact, 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 description coverage is only 33%: projectId is documented in the schema, but q and limit are not. The word 'Search' marginally hints at q's purpose, but limit (1-100) and its default/behavior are completely unexplained in either the schema or 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?

The description states a clear verb ('search'/'list') and resource ('customer-directory contacts'), so the agent knows this returns contact records. It does not, however, differentiate itself from siblings like dealdesk.get_contact or dealdesk.list_companies, which is what would push this to 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?

Phrasing it as 'Search or list' implies two modes (supply q to search, omit it to list), giving implied usage. There is no explicit when-to-use, no when-not, and no mention of the nearest alternatives such as get_contact for a single record.

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 does not disclose pagination behavior (despite a limit param), default ordering, what the response contains, or the project-scoping/auth implication noted only in the schema's projectId 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 zero filler; the resource and its filters come first.

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

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

For a list tool with no output schema and no annotations, the definition is adequate but thin: it omits pagination/default-limit semantics and ordering, which an agent needs to paginate or bound results 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 75%, so the baseline is 3. The description mentions the status and search filters already documented in the schema, and adds nothing for the undocumented limit parameter or the projectId constraint.

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 (List) + resource (quotes) + explicit scope (for a project), so an agent knows this returns a collection rather than a single quote. It does not explicitly distinguish itself from siblings like get_quote or list_quote_shares, keeping it 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?

"Optionally filtered by status or search text" implies the filtering use case, but there is no guidance on when to prefer this over get_quote/get_quote_summary, nor any prerequisite or exclusion. Usage must be inferred.

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 annotations absent, the description carries the full burden. It implies a read operation and reveals that results come as two share-path variants, but says nothing about auth/permission requirements, pagination, or result limits for what could be a growing 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 short sentences, front-loaded with the core action before the explanatory clause. No filler, though the second sentence would earn its place better if it clarified return shape rather than ambiguous field names.

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 2-required-param, no-annotation, no-output-schema read tool, the description gives only the minimum: what it lists and that two share variants exist. Missing are permission assumptions and pagination behavior, which an agent would need before calling it reliably.

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% (quoteId has no description). The description adds no meaning for either parameter, and instead spends its text on classicPath/experiencePath, which are output fields, not inputs — potentially misleading in a parameter-semantics sense.

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 customer share links for a quote.' An agent can tell this is the read side of the share-link family, distinct from create_quote_share/patch_quote_share. It does not name those siblings, but the purpose 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?

No guidance on when to use this versus create_quote_share or patch_quote_share, nor any prerequisites. The only conditional information is about output variants (classicPath vs experiencePath), not about selecting this tool.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read, but the description says nothing about pagination, ordering, whether the result is scoped to a plugin version, or what happens when no skills are shipped. Only the bare minimum is conveyed.

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 efficient, though arguably so terse that it omits useful routing context that would still have earned its place.

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

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

This is a low-complexity, single-parameter, read-only listing tool with full schema coverage and no output schema, so the description need not explain return values. However, it omits any indication of what the returned skills contain or how they relate to the dealdesk-plugin packaging, leaving it only minimally adequate.

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 (must match API key / OAuth project). The description adds no additional parameter meaning, so the baseline 3 applies.

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

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

States a specific verb (List) and resource (shipped DealDesk sales skills packaged with dealdesk-plugin), which is concrete enough for an agent to understand what it returns. It does not differentiate itself from siblings such as dealdesk.discover, which could plausibly surface similar capability information, so it falls 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 prerequisites, and no mention of alternatives. An agent cannot tell from this text whether to call list_skills versus dealdesk.discover for capability discovery.

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 and largely fails to. It says nothing about read-only semantics, ordering, pagination behavior, or what the result set contains for a tool with a limit parameter. The parenthetical is a taxonomy, not behavioral disclosure.

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 tight sentence with the resource and scope front-loaded and zero filler. It is efficient, though it could have used one more sentence to carry behavioral context without bloat.

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 and no annotations, the description should cover more of the tool's behavior. It is adequate on scope but silent on pagination, ordering, and default entity behavior, which is a real gap for a 5-parameter list tool even at 80% 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 80%, so the schema already documents projectId, entityId, cardId, and entityType. The description restates the entity scope and the kinds of updates but adds no meaning about the limit parameter, ordering, or the cardId/entityId alias relationship. 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 resource (status updates), and enumerates what counts as a status update (comments, tasks, touchpoints including email) plus the entity scope (desk card, company, contact). An agent can distinguish this from add_card_note or create_status_update, though it doesn't explicitly contrast with sibling list tools.

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

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

The entity options imply when the tool applies, but there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as get_card or list_cards. Usage is inferable but never 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?

No annotations are provided, so the description carries the full burden. It does disclose that the logged email becomes a touchpoint typed by direction (email_incoming/email_outgoing), which is useful behavioral context, but says nothing about side effects on card status, permission requirements, deduplication, or what the call returns.

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

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

Two sentences, zero filler, with the core action front-loaded before the exclusion rule. 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 10-parameter write/log tool with no annotations and no output schema, the description covers identity and routing but omits return behavior and the required/constraint side (only two of ten params are required; the API/account project match constraint lives in the schema, not the prose). 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 90%, so parameters are largely self-documented. The description's direction→touchpoint-type mapping duplicates what the schema's direction enum already states, adding no syntax or format detail beyond structured fields; 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 (log), resource (email on a desk card), and the resulting artifact (status-update touchpoint typed email_incoming/email_outgoing). It also names the sibling it is not (add_card_note), so an agent can distinguish it from the many note/card tools 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?

Gives an explicit negative routing rule — 'Do not use add_card_note for email logs' — which is the key disambiguation among the sibling set. It lacks positive when-to-use context (e.g. logging correspondence vs. creating a status update directly via create_status_update), so it stops short of a 5.

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

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

With no annotations, the description carries the full burden, and it delivers the most important behavioral fact: changing company/contact also updates a linked local case and quote customer link. It also clarifies the soft-close semantics and that no DELETE exists. It omits permission/auth requirements, idempotency, and return behavior, so it is good but not complete.

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

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

Four dense sentences, front-loaded with the core verb/resource and followed by the highest-risk details (linking, cascade, soft close). The parenthetical cross-references ('same as HTTP accountRef/contactRef', 'same as the DealDesk UI') are useful analogies but slightly verbose.

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-parameter mutation tool with no annotations and no output schema, the description covers the essential update semantics, linking/clearing, cascading side effects, and the soft-close pattern. Remaining gaps (auth, response shape, the deprecated notes alias) are minor given they are partly covered by the schema.

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

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

Schema coverage is 67%, and the description adds real meaning for the trickiest inputs: the accountRef/contactRef equivalence for companyId/contactId and the null-to-clear behavior (including 'clear contact only' nuance). It says nothing about notes (deprecated alias), deskDescription, or the required projectId/cardId, leaving some parameters 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 and resource ('Update a desk card') and enumerates the mutable fields (title, stage, description, company/contact), so an agent knows exactly what operation this performs. It does not explicitly name a sibling it is not (e.g., patch_card_note), so it falls 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?

Gives concrete usage rules: pass companyId/contactId to link Customer Directory records, pass null to clear, and use stage=closed for a soft close since there is no DELETE. These are actionable conditions, though it never states when to prefer this over patch_card_note or patch_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, so the description carries the full burden. It usefully discloses a capability limit (no delete via MCP) and implies optimistic concurrency by steering to updatedAt, but does not explain on-conflict behavior, last-write-wins semantics when expectedUpdatedAt is omitted, permission requirements, or what a successful update returns 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 short sentences, zero waste, with the purpose and the get_card prerequisite front-loaded ahead of the capability caveat. Appropriately sized for the operation.

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 covers the key workflow and delete boundary but leaves gaps: conflict/error behavior, return value (no output schema to fall back on), and any permission notes. Adequate but not 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 description coverage is high (83%), so the schema documents text, title, noteId, projectId and expectedUpdatedAt. The description mentions noteId/updatedAt sourcing but adds little syntax or format detail beyond the schema, which is the expected baseline.

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

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

States a specific verb (Update) and resource (structured desk-card note), clearly distinguishing it from add_card_note (creation) and the sibling patch_company_note/patch_contact_note family by resource scope. An agent can tell what this does without opening 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?

Gives a concrete prerequisite workflow ('Prefer get_card first for noteId and updatedAt') and an explicit capability boundary ('Delete is not available through MCP'). No exclusion/routing toward a specific alternative when the note doesn't exist, but the when-to-use context is clear.

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

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

With no annotations, the description carries the full behavioral burden. 'Update' signals mutation but nothing discloses partial-update semantics (are omitted fields left unchanged?), whether nullable fields can be cleared with null, permission/scope requirements (only hinted at via schema text on projectId), or what the response returns. For a 12-parameter mutation tool 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 front-loaded sentence with no filler is well structured, but it is under-sized for a tool with 12 parameters. The brevity here reflects missing detail 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?

Given no annotations, no output schema, and near-zero schema coverage, the description should do far more. It omits update semantics, permissions, return behavior, and most parameter meaning, leaving an agent unable to call this confidently beyond guessing.

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

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

Schema description coverage is only 8% (just projectId), so the description must compensate, and it only partially does. The parenthetical loosely maps to title, stage, description and estimates, but leaves quoteId, companyId, contactId, ownerUserId, probabilityPercent, and estimatedValueCurrency completely undocumented and never explains null vs. omission semantics.

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 DealDesk case') and enumerates the mutable field categories (title, stage, description, links, estimates), which is more than a tautology. It does not, however, explicitly differentiate itself from the many sibling patch_* tools (patch_card, patch_quote, patch_company, patch_contact) beyond naming the resource.

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 reference to alternatives such as create_case or get_case. The agent is left to infer the 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?

With no annotations, the description carries the full burden, and it does disclose the optimistic-concurrency model (expectedRevision). But it omits the conflict/stale-revision failure behavior, whether this is a genuine partial (patch) update, and any auth/permission context.

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

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

Two tight, front-loaded sentences with no filler; the required precondition is surfaced immediately after the action. Efficient and appropriately sized for what it attempts.

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, no output schema and near-zero schema coverage, the description is far too sparse - it neither enumerates the patchable fields nor explains partial-update semantics or failure modes.

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% (just projectId), so the description must compensate for 10 parameters - and it explains only expectedRevision's purpose. The remaining update fields (legalName, displayName, fields, emailDomains, etc.) are entirely undocumented in both places.

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 (company), and the 'patch' naming plus description distinguishes it from create_company/get_company/list_companies. It does not explicitly name sibling alternatives, but the action is unambiguous.

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

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

It gives a real precondition - expectedRevision must come from get_company - which tells the agent to call get_company first. However it offers no when-to-use guidance versus create_company or other update paths, so usage context is only partially established.

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 safety profile. It usefully discloses that deletion is outside MCP and that noteId/expectedUpdatedAt come from get_company, hinting at optimistic concurrency. It never says what happens on a stale expectedUpdatedAt, whether the update is reversible, or what permissions are required.

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 prerequisite and the scope limit. No filler, though it is terse enough to leave gaps.

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 17% parameter coverage, the description covers the create/delete boundary but leaves conflict behavior, permissions, and most parameters unaddressed. Adequate but clearly 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 description coverage is only 17% across 6 parameters. The description adds meaning only for noteId and expectedUpdatedAt (via the get_company lookup); text, title, companyId, and projectId semantics remain undocumented in both places.

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.' The word 'existing' distinguishes it from the sibling add_company_note, and noteId/updatedAt tie it to the note entity. It stops short of explicitly naming add_company_note as the create-side alternative.

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?

'Prefer get_company first for noteId and updatedAt' gives a concrete prerequisite lookup, and 'Delete is not available through MCP' rules out an operation an agent might otherwise attempt. No explicit when-not guidance or sibling comparison beyond that.

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 discloses the optimistic concurrency requirement (needing expectedRevision) but omits critical details like partial vs full update semantics, error behavior on revision mismatch, required permissions, and what happens to 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?

Two short sentences, front-loaded with the action and then the concurrency prerequisite. No wasted words, though it is arguably too terse for the tool's complexity.

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-parameter mutation tool with no annotations, no output schema, and very low schema description coverage, the description is far from complete. It addresses only the concurrency mechanism and leaves parameter meanings, update semantics, and error handling undocumented.

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 11% (only projectId has a description). The description adds meaning only for expectedRevision by indicating its source, but provides no insight into the other 8 parameters, including the fields object, email, locale, etc.

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 'Update a contact' which is a clear verb+resource, but it essentially restates the tool name and does not differentiate from siblings like create_contact or patch_company. No indication of what fields can be updated or the scope of the update.

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

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

Explicitly states a prerequisite: 'Requires expectedRevision from get_contact for optimistic concurrency.' This tells the agent to call get_contact first and why. No explicit when-not guidance, but for a patch tool the context is clear enough.

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 full behavioral burden. It discloses the delete limitation and hints at optimistic concurrency by pointing to get_contact for updatedAt, but says nothing about required permissions, error behavior, or how partial updates are handled. Useful but incomplete.

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 filler, and the preconditions precede the negative constraint. Every sentence carries actionable information.

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

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

For a 6-parameter mutation tool with no annotations and no output schema, the description covers routing and the delete exclusion but leaves concurrency semantics and parameter meanings thin. Adequate minimum viable, not 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 only 17% of 6 parameters. The description only hints at noteId and updatedAt; text, title, contactId, and the semantics of expectedUpdatedAt (conflict behavior, date format) are left undocumented in both schema and 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 ('Update an existing contact note'), which cleanly separates it from add_contact_note. It does not name sibling tools directly, but 'existing' implies the note must already exist, so an agent can route correctly without opening 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?

Explicitly tells the agent to call get_contact first to obtain noteId and updatedAt, and states the negative constraint that delete is not available through MCP. That is real when-to-use guidance, though it doesn't distinguish this tool from patch_card_note/patch_company_note.

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 draft-only constraint (accept/decline refused) and that pricing lines are untouched, which is genuine boundary context for a mutation. But it omits auth/permission requirements, whether unspecified fields are left unchanged (patch semantics), and reversibility.

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 dense sentences with the scope and the key exclusion front-loaded; no filler. Slightly terse given the 11-parameter surface, 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 an 11-parameter, nested-object mutation with no annotations and no output schema, the description is only partially complete. It covers the scope and two exclusion rules but leaves snapshot object structure, nullability, auth/project-scoping, and error behavior unexplained.

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% (only status and projectId are documented), so the description should compensate more. It names five updatable field groups but omits opportunityId, accountSnapshot, and contactSnapshot, and adds no format or constraint detail beyond the schema field names.

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

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

States a specific verb+resource ('Update draft quote metadata') and enumerates the field groups affected (title, language, currency, customer snapshots, experience template). It also distinguishes itself from pricing mutations via 'does not replace pricing lines' (cf. replace_quote_items). Clear, though it does not name the sibling tools for the excluded actions.

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

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

Provides when-NOT guidance ('does not accept/decline and does not replace pricing lines'), which implies which siblings to use instead. However, it names no explicit alternative tools and gives no positive when-to-use context (e.g., quote must be in draft 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?

With no annotations, the description carries the full behavioral burden. It usefully discloses that isOpen=false closes the link without deleting it, which is important mutation context. However, it omits auth/permission requirements, whether the update is partial, what happens to omitted fields, and whether any destructive side effects exist.

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

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

Two tight sentences with no wasted wording. The primary operation is front-loaded, followed immediately by the most important behavioral note about closing rather than deleting.

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 gives the basic operation and one important side-effect detail. It is still thin on required IDs, partial-update semantics, and permission requirements, which leaves meaningful 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 description coverage is only 43%, so the description must compensate. It names the updatable fields (label, password, quickchat, isOpen) and maps quickchat to quickchatEnabled, but does not explain the required projectId, quoteId, or shareId, nor the password-clearing behavior already noted in 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: updating a quote share link. It enumerates the mutable fields (label, password, quickchat, isOpen), so an agent can distinguish it from list_quote_shares and create_quote_share 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 description implies usage through 'Update a quote share link' and gives one operational guideline: set isOpen=false to close the link. It does not explicitly say when to use this instead of create_quote_share, list_quote_shares, or other quote-share siblings, and there are no 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?

No annotations are provided, so the description carries the full burden. It usefully discloses the authorization model (authors edit own comments/touchpoints, tasks by staff) and implies optimistic concurrency via the updatedAt recommendation. However, it never explains PATCH/partial-update semantics, what happens to omitted fields, or any destructive behavior for this 17-parameter 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?

Three tight sentences, front-loaded with the purpose, then permissions, then the workflow hint. 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 mutation tool with 17 parameters, no annotations, and no output schema, the description covers the workflow and auth well but leaves return values, partial-update behavior, and most parameter meanings unaddressed. 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 description coverage is low (35%), so the description should compensate. It groups the parameters into three conceptual surfaces (comment/task/touchpoint), which helps an agent understand the polymorphism, but it does not clarify the many undocumented fields (note, dueAt, subject, contactIds, occurredAt, recurrence, participants, assigneeUserId, touchpointType, mentionedUserIds).

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 (an existing status update), and enumerates the three editable surfaces (comment body, task fields/status, touchpoint fields). 'Existing' clearly distinguishes it from create_status_update and list_status_updates among the siblings.

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

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

Names the alternative explicitly ('Prefer list_status_updates first for statusUpdateId and updatedAt') and states the condition that selects it, plus the edit authorizations. It stops short of stating when-not-to-use or other alternatives, but the routing guidance is clear.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does state that the operation is side-effect free, which is a useful safety trait, but it omits auth requirements, expected output shape, error behavior, and whether evaluation reads only the current portfolio state or can validate against a specific revision. One useful trait is not enough for a tool with a nested configuration object and no output 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?

The description is a single, front-loaded sentence with no wasted words. It is appropriately concise, though the phrase 'against the Portfolio' is somewhat opaque and the sentence could be sharpened with a brief outcome clause.

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

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

Given a nested, undocumented configuration object, no output schema, no annotations, and four parameters, the description is materially incomplete. It does not explain what evaluation produces, what the configuration must contain, or how the result should be interpreted. A caller would need to inspect schemas or experiment to use this tool correctly.

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

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

Schema description coverage is only 50%, with projectId and revisionId documented in the schema while configuration and locale are not. The description adds no parameter-level meaning at all, so it fails to compensate for the undocumented nested configuration object or the locale parameter. An agent gets no help from the description beyond what the partial schema already provides.

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

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

The description states a specific verb (Evaluate) and resource (a CPQ configuration against the Portfolio), so the general purpose is clear. It also flags the operation as side-effect free, helping distinguish it from mutation-oriented siblings like create_quote or patch_card. However, it does not explain what 'evaluate' actually checks or returns, leaving the exact outcome ambiguous.

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

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

There is no explicit guidance on when to choose this tool over alternatives such as portfolio_summary, create_quote_from_configuration, or update_quote_from_configuration. The parenthetical 'side-effect free' implies a safe dry-run use case, but the description does not state prerequisites, exclusions, or decision criteria. This falls short of even implied usage guidance.

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

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

No annotations are provided, so the description carries the full disclosure burden, yet it says nothing about required scope/permissions, whether the operation is read-only, or what the draft vs published summary contains. The only behavioral hint (project must match the API key/OAuth project) 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 short sentence with the resource front-loaded and no filler. It is efficient, though arguably under-specified rather than genuinely concise.

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 no annotations, no output schema, and an undocumented locale parameter, the description should explain what the summary returns and what locale controls. As written, an agent lacks enough information to invoke it confidently beyond the required projectId.

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 the locale parameter has no description anywhere. The tool description adds no meaning about locale (e.g., which languages are supported or default behavior), so it 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 gives a verb (Get) and a resource (Portfolio draft/published summary for a project), which is more than a tautology. However, 'Portfolio' is left undefined and the description does not distinguish this from sibling dealdesk.portfolio_evaluate, so an agent cannot tell the two apart 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?

There is no guidance on when to use this tool versus dealdesk.portfolio_evaluate or any other summary tool, and no stated prerequisites. 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 burden. It usefully discloses that rendering only applies in MCP Apps hosts (ChatGPT) and that it is a UI render rather than data, which is meaningful context. However, it omits what happens outside a host, whether any state is mutated, or any permission requirements, leaving notable 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 short, front-loaded sentences with no filler. The purpose and the routing cue to get_card are both presented immediately, and every sentence earns its place.

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

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

An output schema exists, so return values need not be explained, and the description covers the core purpose and selection condition. It is complete enough to call correctly, with only minor gaps around host prerequisites and parameter details.

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 documented in the schema, cardId is not. The description adds no parameter-level meaning (e.g., format or sourcing of cardId), so it does not compensate for the uncovered parameter. This sits at the adequate baseline.

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

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

States a specific verb and resource: it renders the DealDesk card-summary widget. It distinguishes itself from data siblings by naming get_card, so an agent can tell it apart without opening schemas. Only slightly held back from 5 by not clarifying the widget's scope beyond 'card-summary'.

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 when to call it ('when the user should see the card UI') and contrasts it with the data tools ('Data tools like get_card return JSON only'). That is clear context and a named alternative, though it stops short of stating when NOT to use it (e.g., non-host environments).

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 real context: it writes to a specific exports folder, returns a file path, and does not persist the PDF on the quote. However it omits auth requirements, whether the file is overwritten, and any rate or side-effect caveats that a no-annotation tool would benefit from.

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 primary action and followed by the persistence caveat. Nothing is wasted, though the second clause is the only non-obvious detail.

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 render tool it covers the action, destination, and return value adequately. It is less complete on how selectedOptionIds affects output and on the API-key/project matching, which are relevant given no annotations and no output schema.

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

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

Schema description coverage is only 67%, and the description adds no meaning for any of the three parameters. It does not explain quoteId, the projectId/API-key matching constraint, or what happens when selectedOptionIds is omitted, so the coverage gap is not compensated.

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/render) and resource (quote PDF), plus the output location (project exports folder) and return value (file path). It is reasonably distinguishable but does not explicitly differentiate itself from siblings like render_quote_totals or render_card_summary.

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 says what the tool does but gives no guidance on when to use it versus alternatives such as get_quote or render_quote_totals, nor any prerequisites or exclusions. Usage must be inferred 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 disclosure burden. It usefully notes the host requirement (MCP Apps hosts / ChatGPT) and that get_quote returns JSON only, but omits what happens on non-supporting hosts, auth needs, or fallback 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 tight sentences, front-loaded with the action, and each sentence carries distinct information (what it does, when to call, alternative). 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?

An output schema exists, so return-format explanation isn't needed, and the host requirement plus usage routing give decent coverage. However, the undocumented quoteId and unstated fallback/error behavior leave an agent with gaps for a rendering 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, but quoteId has no schema description, and the tool description adds no parameter meaning at all. The description fails to compensate for the undocumented required quoteId 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 distinguishes itself from the JSON sibling get_quote. It's clear this renders a UI widget rather than returning data, though it doesn't differentiate from the related render_quote_pdf sibling.

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 call it ('when the user should see quote totals UI') and names the alternative (get_quote returns JSON only). Lacks an explicit when-not-to-use clause, but the routing condition is clear enough for 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?

With no annotations, the description carries the burden and does well: it discloses replace-vs-merge semantics ('Send the full arrays you want persisted'), the draft-only precondition, and the refusal case for accepted/declined quotes. It omits permission/auth requirements and how priceConfirmations interact with the write.

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

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

Three short sentences, front-loaded with the core action and immediately followed by the critical precondition. 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 not be explained. For a destructive multi-array write the description covers semantics and preconditions adequately, though a note on auth/locking or the interaction with priceConfirmations would close the 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 only 33% across 6 params. The description names lineItems, options, and groups and clarifies they are full-replacement arrays, which adds real value, but leaves the shape of those free-form objects, plus projectId/quoteId and priceConfirmations, undescribed beyond the sparse 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 ('Replace draft quote lineItems, options, and groups') and names the exact entities affected, so it is distinguishable from generic quote tools like patch_quote. It stops short of naming which sibling to use instead when the quote is not a draft or not classic authoring.

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 applicability context: draft-only, refused for accepted/declined quotes, and 'classic authoring'. The parenthetical implies a contrast with configuration-based authoring tools but never names an alternative such as update_quote_from_configuration or patch_quote.

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 flags a "full commercial replace" (destructive scope), bounds the blast radius ("Does not change title/customer/ownership"), and notes quoteLayout affects presentation. It omits auth requirements and any reversibility/error 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 and constraints front-loaded; every clause earns its place. Slightly terse given the parameter count, but 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 not be explained, and the description covers scope and non-changes well. But for an 8-parameter nested-object tool with 25% schema coverage, the parameter surface remains materially under-described.

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 25% across 8 parameters. The description mentions only quoteLayout and does not explain configuration, portfolioRevisionId, priceBookRevisionId, currency, or locale, leaving most of the nested/required inputs undocumented in both places.

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?

"Re-apply a published Portfolio configuration onto an existing draft quote" names a specific verb and resource, and the phrase "onto an existing draft quote" implicitly contrasts with create_quote_from_configuration. It is clear what the tool does, though it does not explicitly name the sibling it competes with.

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 precondition "existing draft quote" narrows the applicable context, and "published Portfolio configuration" hints at required inputs. However, there is no explicit statement of when to choose this over create_quote_from_configuration or replace_quote_items, nor any exclusion of non-draft quotes.

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