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 for a mutation tool, yet it never states side effects (record creation, webhook/notification triggers), auth or scope requirements, or error behavior. Its one behavioral claim — that the note is plain HTML passed without a CDATA wrapper — duplicates the note parameter's schema description rather than adding new 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 short sentences with the core purpose front-loaded and no filler — effectively sized. The second sentence, however, restates schema content, so one of the two sentences does not fully 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 a 13-parameter create tool with no annotations, no output schema, and roughly half the parameters undocumented, the description is far too thin to be complete. It gives no linkage semantics (which IDs link the activity to deals/persons/orgs/leads) and no post-creation behavior.

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

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

Schema description coverage is only 46%, so the description should compensate for the undocumented parameters (org_id, deal_id, lead_id, user_id, location, person_id, duration, etc.). Instead it addresses only 'note' and repeats what the schema already says, leaving most of the 13 parameters unexplained in either place.

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

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

States a specific verb+resource ('Create a new activity') and names concrete instances (call, meeting, task), which cleanly separates it from siblings like activities_get, activities_update, activities_list, and activities_mark_done. It stops short of explicitly routing the agent between create vs. update/mark_done, so it is clear but not sibling-differentiating.

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

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

There is no when-to-use guidance in the description, no prerequisites, and no mention of alternatives such as activities_update or activities_mark_done. The only routing hint ('call pipedrive_activity_types_list first') lives in the schema, not the description, so the description itself offers no contextual guidance.

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

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

With no annotations provided, the description carries the burden and does disclose two useful behaviors: the explicit confirmation token gate and a dry-run preview mode. It omits what deletion actually destroys (linked notes, deal associations), permission requirements, and reversibility, which matters for an irreversible 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 short sentences with the core action front-loaded and zero filler. It is efficient, though the telegraphic style leaves the confirm/dry_run mentions as bare facts rather than integrated 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 destructive tool with no annotations and no output schema, the description covers the confirmation guard and preview mode but is silent on consequences, permissions, and error behavior. It is minimally adequate rather than 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 100%, so activity_id, confirm, dry_run and reason are all already documented with types, const, default and notes. The description only restates confirm and dry_run, adding no syntax or meaning beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ("Delete an activity") so the agent immediately knows the operation. It does not, however, distinguish itself from nearby siblings such as pipedrive_activities_mark_done or pipedrive_activities_update, which an agent could confuse with deletion.

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 a guarded destructive workflow (must pass confirm: "DELETE", dry_run available) but never says when to prefer this over mark_done/update or when deletion is appropriate. Usage is inferable from the operation name 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, description should disclose behavioral traits. It only restates the obvious (get by ID), missing info on read-only nature, authentication, rate limits, or 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?

Single sentence with no wasted words. Efficiently conveys the essential information for a simple retrieval 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?

For a simple get with one parameter and no output schema, the description is mostly sufficient. It could mention that it returns the full activity object, but the agent can infer this from the tool's purpose.

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

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

Schema coverage is 100% with parameter description already present. Description does not add extra meaning beyond the schema. Baseline score is appropriate.

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

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

Description clearly states the verb 'Get', resource 'activity', and qualifier 'single by ID'. It distinguishes from siblings like pipedrive_activities_list which retrieves multiple activities.

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 tool versus alternatives. Lacks context on prerequisites (e.g., needing an existing activity ID) or when to prefer get over 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?

No annotations are provided, so the description carries the full behavioral burden. It only mentions 'pagination' generically and says nothing about permissions, whether results are scoped to the authenticated user, default sort order, or what the response contains.

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

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

A single front-loaded sentence with no filler or redundancy. It is efficient, though the brevity contributes to the missing guidance rather than being 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 an 11-parameter list tool with no annotations and no output schema, the description is too thin. It leaves the agent without scope, default behavior, or result-format expectations that annotations or an output schema would otherwise supply.

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

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

Schema description coverage is 100%, with every one of the 11 parameters documented inline (enums, ranges, defaults). The description adds nothing beyond the schema's own 'filters and pagination' framing, 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 (activities), so the core operation is unambiguous. However, it does nothing to distinguish itself from siblings like pipedrive_my_upcoming_activities or pipedrive_my_overdue_activities, which are also activity lists.

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 indication of when to prefer this over the scoped activity-list siblings. The agent must infer usage entirely from the name and schema.

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?

Without annotations, the description must disclose behavioral traits. It only says 'Mark', implying mutation, but omits side effects, permissions, error states, or 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?

The description is a single sentence, concise but lacks structure. It could be improved by front-loading the core action and adding brief context.

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 toggle operation, the description misses key details: what happens if activity is already in requested state, required user permissions, and return value. Completeness is lacking.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond what the schema already provides, so baseline score of 3 applies.

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

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

The description clearly states the action (Mark) and the resource (activity) with the state change (done/undone). It is specific enough to distinguish from sibling tools like create, delete, get, list, update, though it does not explicitly name them.

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

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

No guidelines are provided regarding when to use this tool versus alternatives. The description does not mention prerequisites, context, or conditions for use.

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 the note field is raw HTML with no CDATA wrapper, but says nothing about permission requirements, whether omitted fields are cleared or preserved, reversibility, or rate limits for a mutation endpoint. One behavioral detail is not enough for a 14-parameter write tool.

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

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

Two short sentences, front-loaded with the core action and no filler. The second sentence is arguably redundant with the schema's note description, but it is not 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 14-parameter mutation with no annotations, no output schema, and 21% parameter coverage, the description is far too thin. An agent has no basis for deciding which fields to send, what happens to unsent fields, or whether it needs activity-type discovery first.

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 21% (activity_id, note, type), leaving 11 parameters (done, org_id, deal_id, lead_id, subject, user_id, due_date, due_time, duration, location, person_id) undocumented in both schema and description. The note/HTML remark in the description largely repeats the schema's own note description, so it adds little compensation 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 (update) and resource (an existing activity), so it is distinguishable from pipedrive_activities_create, pipedrive_activities_delete and pipedrive_activities_get. It does not, however, mention how it relates to the overlapping pipedrive_activities_mark_done sibling, whose job overlaps with the `done` parameter 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?

There is no guidance on when to update versus mark an activity done, no statement about partial vs. full replacement semantics, and no mention of prerequisites such as needing the activity ID to exist. The only inference available is the implied 'this changes an existing 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 disclosure burden. 'List the activity type key_strings configured for this workspace' makes the read-only, non-mutating nature and workspace scoping clear, though it does not explicitly state permissions or that no side effects occur.

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

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

Two sentences, no filler. The resource is described first and the usage condition second, which is the correct front-loaded ordering.

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 parameterless reference-lookup tool with no annotations and no output schema, the description covers what the tool does and when to invoke it. It could add a note on the returned shape (e.g., key_string plus display name), but what is present is largely sufficient.

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

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

The tool takes zero parameters, which sets the baseline at 4. There is nothing further to document, and the description's mention of 'key_strings' clarifies what the null-input call consumes and returns.

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 ('activity type key_strings'), plus the scope constraint ('configured for this workspace'). It is clearly distinguishable from siblings like pipedrive_activities_list, which returns activity records rather than the type vocabulary.

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 when to call it: 'before creating an activity if you aren't sure which "type" values are valid.' This names both the trigger condition and the downstream dependency, leaving nothing 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 provided, so the description carries the full burden. It discloses what is returned (keys, names, types, options) and implies a read-only listing via "List," but says nothing about the metadata caching behavior (refresh_cache), pagination semantics, or rate limits that matter for a paged read tool.

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

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

Three tight sentences with zero filler: purpose first, return shape second, routing guidance third. The most actionable information (what it lists and what it returns) is front-loaded.

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

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

With no annotations and no output schema, the description usefully fills the biggest gap by describing the return payload (keys, names, types, options). Pagination behavior and cache semantics are only covered by the schema, which is acceptable, but a note on when a refresh is warranted would complete the picture.

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

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

Schema description coverage is 100%, so all five parameters, including the entity_type enum and the limit/cursor/refresh_cache/include_options fields, are already documented in the schema. The description adds no syntax or format detail beyond what the schema provides, so the baseline of 3 is correct.

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

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

The description states a specific verb and resource ("List field metadata for an entity type") and immediately discloses the returned content (field keys, names, types, enum options). It also names a companion tool, custom_fields_by_name, which an agent can use to distinguish this discovery tool from the consumer tool.

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

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

It gives an explicit when-to-use condition ("Use this to discover available custom fields before using custom_fields_by_name") and names the alternative tool. It stops short of stating when-not to use it, so it falls just short of full routing guidance.

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

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

No annotations are provided, so the description carries the full behavioral burden. It implies a read but does not disclose pagination behavior (limit/cursor), result ordering, empty-result handling, or whether mail sync/permissions affect results. For a no-annotation tool this is a notable gap.

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

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

A single short sentence with no filler and the resource/scoping front-loaded. It is efficient, though its brevity comes at the cost of any routing or behavioral 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 paginated list tool with fully documented params and no output schema, the description is minimally adequate. It omits the differentiation from sibling mail-message listers and any hints on results, which an agent 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 description coverage is 100%, so deal_id, limit, and cursor are already documented in the schema. The description adds no extra semantics (e.g., deal_id format, default paging) beyond that, 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 (mail messages) with a scoping qualifier (linked to a deal), so the agent knows what it returns. It does not distinguish itself from similar siblings like pipedrive_person_mail_messages_list or pipedrive_mail_thread_messages_list, leaving the agent to infer the difference from names 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?

There is no explicit when-to-use guidance, no prerequisite for how a deal_id is obtained, and no naming of the alternative mail-message listers that would help the agent pick this one. The description simply restates the operation without routing context.

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

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

No annotations are provided, so the description carries the full burden. It implies a mutation ('attach') but never states permission requirements, what happens when a product is already attached, whether the call is idempotent, or what the response contains. For a write tool with zero annotation coverage 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 core action front-loaded and no filler. It is efficient, though arguably too terse given the tool's 8-parameter 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 mutation tool with 8 parameters, no annotations, and no output schema, the description is far too thin. It leaves undocumented parameters, side effects, and error/return behavior entirely unaddressed.

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

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

Schema coverage is only 63%, and the description adds nothing beyond echoing 'price/quantity'. Optional parameters like discount, tax_method, comments, and product_variation_id are left entirely to the (partially undocumented) schema, so the description fails to compensate for the coverage gap.

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

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

States a specific verb+resource ('Attach a product to a deal') and hints at the key fields (price/quantity), so an agent immediately knows the operation. It does not, however, distinguish itself from the sibling pipedrive_deal_products_update or explain the relationship to product_variations.

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

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

There is no guidance on when to use this versus pipedrive_deal_products_update or pipedrive_deal_products_list, nor any stated prerequisites (e.g., the deal and product must already exist). The agent must infer all usage context.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does add value by flagging the mandatory confirmation string and dry_run preview, but says nothing about irreversibility, required permissions, or side effects (e.g., deal value recalculation) for a destructive mutation.

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

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

Three short, front-loaded fragments with no filler — the core action comes first, followed by the two operational caveats. Telegraphic style leaves no wasted words, though it is terse to the point of terseness rather than fully structured prose.

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

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

For a destructive mutation with no annotations and no output schema, the description covers the confirmation and preview mechanics but omits expected return behavior and the consequences of deletion. It is adequate but leaves meaningful gaps for a delete operation.

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 every parameter (confirm, dry_run, deal_id, deal_product_id, reason) is already documented in the schema. The description merely restates confirm and dry_run without adding syntax or format detail beyond it.

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 ('Remove a product from a deal'), which is unambiguous on its own. It doesn't explicitly differentiate from sibling pipedrive_deal_products_update, though the verb 'remove' naturally contrasts with add/update.

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

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

The mention of 'Requires confirm: "DELETE"' and 'Supports dry_run' implies the intended workflow (confirm first, optionally preview), but there is no explicit when-to-use guidance or routing away from sibling tools like pipedrive_deal_products_update.

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. 'List' implies a read-only operation, but the description says nothing about pagination behavior (cursor/limit), rate limits, permissions, or what the response contains. This is a significant gap for a tool with zero annotation coverage.

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

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

The description is a single, front-loaded sentence with zero wasted words. It is appropriately sized for a simple list endpoint, though its brevity contributes to gaps in other dimensions.

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

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

For a straightforward list tool, the required deal_id and pagination parameters are documented in the schema, and no output schema exists. However, with no annotations and no usage context, the description is minimally adequate but does not help an agent understand when or why to call this tool over its siblings.

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

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

Schema description coverage is 80%, so the schema already documents most parameters, including limit, cursor, and deal_id; only sort_by lacks a description. The description adds no parameter meaning beyond the one-sentence purpose, so the baseline 3 for high coverage 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 ('products attached to a deal'), which clearly implies the direction of the relationship versus the sibling pipedrive_product_deals_list. However, it does not explicitly name or differentiate from any sibling tool, leaving the agent to infer the distinction.

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 no guidance on when to use this tool versus alternatives such as pipedrive_product_deals_list or pipedrive_products_list. It also omits prerequisites like required permissions or whether the deal must exist.

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

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

With no annotations provided, the description carries the full burden. 'Update' implies mutation, but nothing is said about partial vs. full update semantics, whether omitted fields are cleared, required permissions, or reversibility. For a mutation tool with zero annotation coverage, 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 front-loaded sentence with no wasted words, but for an 8-parameter mutation it is under-specified rather than genuinely concise. Brevity here comes at the cost of usefulness.

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

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

Given 8 parameters, low schema coverage, no annotations, and no output schema, the description is far too thin. An agent gets no field semantics, no update behavior, and no return expectations.

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

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

Schema description coverage is only 38% — 6 of 8 parameters (comments, discount, quantity, item_price, tax_method, product_variation_id) lack schema descriptions. The description names no parameters at all, so it fails to compensate for the coverage shortfall on this 8-param tool.

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 (product attachment on a deal), which is distinguishable from siblings like pipedrive_deal_products_add, _delete, and _list. It's clear but does not explicitly name or contrast against those 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?

No guidance on when to use this versus pipedrive_deal_products_add, _delete, or pipedrive_deals_update. No prerequisites (e.g., the deal product must already exist) are stated, leaving the agent to infer context.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it discloses almost nothing: no permission/auth requirements, no mention of side effects such as triggering webhooks or affecting deal counts, no deduplication behavior, and no return information. Only 'create' implies mutation; the mutation semantics themselves are undocumented.

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

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

Two compact sentences, front-loaded with the core action and then the two special-case input mechanisms. No filler, no repetition of the tool name.

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

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

For a 13-parameter write tool with no annotations, no output schema, and 38% schema coverage, the description is too thin. An agent still lacks guidance on required companion IDs, visibility/permission implications, and typical success/failure behavior.

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

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

Schema description coverage is only 38% across 13 parameters, so the description should compensate. It adds genuine meaning for custom_fields (key vs human-readable name), custom_fields_by_name, and label_ids (IDs or names, replaces existing labels), but says nothing about value, org_id, status, currency, stage_id, person_id, pipeline_id, visible_to, or expected_close_date.

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 new deal') and immediately scopes the two non-obvious capabilities it supports: custom fields by name or key, and the native Label field via label_ids. It implicitly distinguishes itself from pipedrive_deals_update/deals_get, but never names those siblings explicitly.

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

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

No when-to-use guidance, no prerequisites (e.g. needing a pipeline/stage or person/org before creating), and no mention of how it relates to pipedrive_deals_update or the search/list siblings. The only routing hint is the note that labels go in label_ids rather than a custom field, which is really a parameter detail.

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

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

No annotations are provided, so the description carries the full burden. It discloses the confirmation requirement and dry_run preview behavior, which is useful. But it doesn't state whether deletion is permanent or reversible, what permissions are required, or what happens to associated entities (activities, notes, products). For a destructive operation, these are meaningful 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?

Two short sentences, no wasted words, front-loads the action and the required confirmation. Highly 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?

For a destructive tool with no annotations and no output schema, the description is too thin. It omits critical behavioral facts: permanence, required permissions, side effects on related records, and whether dry_run returns output schema information. The confirmation mechanism is covered, but the overall picture is incomplete.

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

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

Schema coverage is 100%, so the schema already documents all four parameters (deal_id, confirm, dry_run, reason). The description adds a high-level summary but doesn't provide additional meaning beyond what the schema already conveys. Baseline 3 is appropriate when the schema fully documents 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 (Delete) and resource (a deal), immediately distinguishing it from siblings like pipedrive_deals_get, pipedrive_deals_update, or pipedrive_deals_move_stage. No ambiguity about what the operation does.

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

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

The description explains the guardrails (confirm must equal "DELETE", dry_run available for preview), which implies when to use each mode. However, it doesn't mention alternatives (e.g., pipedrive_deals_update for archiving) or when deletion is preferable. Usage is implied rather than explicitly guided.

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. 'Get' implies a read-only lookup and 'resolved custom fields' hints at how custom data is returned, but there is no mention of error behavior for invalid/inaccessible IDs, permissions, or rate limits.

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 the action, the key lookup, and the notable return content. 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 getter with no output schema, the description conveys what comes back ('full details including resolved custom fields'). It is adequate, though it could note that include_fields/custom_field_keys control the extra response content.

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 deal_id, include_fields, and custom_field_keys are already documented in the schema. The description only loosely gestures at custom fields and adds no syntax or format detail beyond the structured fields, matching the baseline for fully-covered schemas.

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 ('Get a single deal by ID') and scope ('full details including resolved custom fields'). The 'single deal by ID' phrasing implicitly distinguishes it from the list/search siblings, but no sibling is named explicitly.

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

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

Usage is only implied: an agent can infer this is for retrieving one known deal rather than browsing or searching. There is no explicit statement of when to prefer this over pipedrive_deals_list, pipedrive_deals_search, or pipedrive_deals_summary.

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 return shape (compact summaries with IDs, titles, stages, values, linked entity IDs) and implies pagination, but says nothing about authorization scope, rate limits, or whether filtering is server-side. For a 16-parameter read tool with zero annotation coverage this is thin.

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

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

Two sentences, no filler, and it front-loads the core action and the return contract. Every clause earns its place.

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

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

With 16 optional parameters, no output schema, and no annotations, the description covers the basics (listing, filtering, pagination, return fields) but leaves the agent without routing guidance versus sibling list/search/summary tools and without any filter-combination or empty-result behavior.

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

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

Schema description coverage is 100%, so all 16 parameters are already documented in the schema. The description adds no filter-specific semantics or interaction rules (e.g. how ids combines with status, or how filter_id interacts with other filters), 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 and resource ('List deals') plus the two operational dimensions (filters, pagination) and the return shape. It is clear and not tautological, but it never distinguishes itself from close siblings like pipedrive_deals_search, pipedrive_deals_summary, or pipedrive_my_open_deals.

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 at all. With sibling tools such as pipedrive_deals_search, pipedrive_my_open_deals, and pipedrive_stale_deals in the same family, the description gives the agent no condition for choosing this tool over those.

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 says 'move'. It does not disclose whether the operation is reversible, whether it requires write permissions, whether it triggers stage-change automations or activity logging, or what the response contains. For a mutation tool with zero annotation coverage 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, front-loaded sentence with no filler; the optional-pipeline caveat is parenthetically scoped rather than buried. Every word earns its place.

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

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

For a mutation tool with no annotations and no output schema, the description omits permissions, side effects, reversibility, and the relationship between stage_id and pipeline_id. It is not complete enough for an agent to invoke it confidently in edge cases.

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

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

Schema description coverage is 100%: deal_id, stage_id and pipeline_id are each documented in the schema. The description's '(and optionally pipeline)' adds a mild hint about pipeline_id being conditional, matching the schema, but nothing beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb ('move') and resource ('a deal') plus the target attribute ('stage', optionally 'pipeline'), so an agent knows exactly what operation is performed. It does not differentiate itself from the sibling pipedrive_deals_update, which could also plausibly alter a deal's stage, leaving the boundary implicit.

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 specialized move tool versus the generic pipedrive_deals_update, nor any mention of prerequisites such as needing a valid stage_id from pipedrive_stages_list or that the stage must belong to the target pipeline. The agent must infer all of this.

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 return behavior beyond the schema ('matching deals with relevance scoring'), which is useful, and the verb 'search/returns' implies a safe read. It says nothing about permissions, rate limits, or pagination semantics (cursor handling), which the schema only partially covers.

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

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

Two short sentences with the core action front-loaded and zero filler. It is efficient, though arguably too terse given the tool's 9-parameter surface.

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

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

For a 9-parameter search tool with no output schema, the description is only partially complete: it gestures at the return shape (relevance-scored matches) but omits pagination behavior and any hint that filtering by status/person/organization is supported. 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 100% across all 9 parameters, so the schema already documents term, limit, cursor, fields, status, person_id, exact_match, include_fields, and organization_id. The description adds no parameter-level meaning beyond what the schema provides, 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 (search) and resource (deals) plus the search mode ('by term'), so the agent knows this is keyword search rather than a full listing. However, it does not distinguish itself from close siblings such as pipedrive_deals_list, pipedrive_deals_get, or pipedrive_deals_summary, so sibling disambiguation is left to inference.

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

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

The phrase 'Search deals by term' implies usage (use when you have a keyword to match), but there is no explicit when-to-use, when-not-to-use, or named alternative among the many deal siblings. An agent must guess between this and deals_list/deals_get for retrieval tasks.

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. 'Get' implies a read, and it discloses what each mode returns (stage counts; optional activities/notes/products), but says nothing about permissions, rate limits, pagination, or result size for a 10-parameter aggregation tool.

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

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

Three tight sentences, front-loaded with the tool's purpose before the mode-switching detail. Every sentence carries information; no filler.

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

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

For a 10-parameter tool with no annotations and no output schema, the description explains the two modes and the optional includes but leaves most filter parameters and the response shape unaddressed. Adequate minimum, but gaps remain that an agent must probe.

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 20%, so six-plus parameters (org_id, status, stage_id, person_id, pipeline_id, include_recent_activities) have no documentation anywhere. The description adds meaning for deal_id and the include_* flags ('with optional activities/notes/products'), partially compensating, but the filter parameters remain 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?

The description states a specific verb and resource ('Get a Claude-friendly deal or pipeline snapshot') and clearly delineates two operating modes based on deal_id. It does not, however, differentiate itself from close siblings such as pipedrive_deals_get or pipedrive_my_pipeline_summary, leaving the agent to infer which summary tool applies.

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

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

It gives explicit mode-selection guidance: pass deal_id for a single-deal summary, omit it for a pipeline overview. That covers internal branching but offers no cross-tool guidance, no mention of when to prefer pipedrive_deals_get, pipedrive_my_pipeline_summary, or pipedrive_deals_list instead.

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 mutation but says nothing about permission/ownership requirements, whether this is a partial update, how omitted fields are treated, or reversibility. The one behavioral detail (label_ids replaces existing labels) is already stated 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?

Two tight sentences with the core purpose front-loaded and no filler. Nothing wasted, 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 14-parameter mutation tool with no annotations, no output schema, and 36% param coverage, the description is far too thin. It omits update semantics, permission expectations, and error/partial-failure behavior an agent would need to call it correctly.

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

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

Schema description coverage is low (36%) across 14 parameters, so the description should compensate. It only addresses custom fields and the label field, leaving title, value, status, stage_id, pipeline_id, person_id, org_id, currency, and expected_close_date 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 deal'), which cleanly separates it from pipedrive_deals_create, pipedrive_deals_delete, and pipedrive_deals_move_stage. It does not explicitly name any sibling, but the CRUD verb makes the distinction inferable.

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 alternatives named, and no prerequisites (e.g., when to prefer deals_move_stage over stage_id here). It only restates the capability, leaving the agent to infer context.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose that the return includes metadata plus an optional (temporary) download URL, which is useful, but it says nothing about permissions, error behavior, or what metadata fields are returned.

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 core action and the optional output are both stated immediately.

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

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

No output schema and no annotations exist, so the description is the only guide. It covers the action and the optional URL but omits the shape of the returned metadata and any auth or error context, leaving it 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%, so both parameters are already documented in the schema. The description only restates that the download URL is optional, adding no syntax or format detail beyond the structured fields, making the baseline 3 appropriate.

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

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

The description states a specific verb and resource ('Get file metadata') and adds scope ('optional download URL'). It is clearly distinguishable from siblings like pipedrive_files_list and pipedrive_files_upload, 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?

There is no guidance on when to use this tool versus pipedrive_files_list or how to obtain a valid file_id. The agent must infer usage entirely from the name and schema.

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 almost nothing. Pagination, sort behavior, permissions, and result shape are all unmentioned; only the schema's cursor/limit params hint at paging. This is a significant gap for a nine-parameter listing tool.

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

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

A single short sentence is front-loaded and waste-free, but for a nine-parameter tool with no annotations and no output schema it is arguably too terse rather than genuinely concise. It is appropriately sized only in the loosest sense.

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 convey more about return behavior and filtering semantics, but it does not. The high schema coverage mitigates the parameter gap, yet the absence of any behavioral or return context leaves the definition incomplete for a listing endpoint.

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

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

Schema description coverage is 89%, so the schema already documents each filter (org_id, deal_id, person_id, etc.) and the pagination params. The description adds only the abstract notion of entity scoping, which is marginal value beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('List files') and adds a scoping hint ('optionally scoped to an entity'), which distinguishes it from the singular pipedrive_files_get. However, it does not name or contrast the sibling, and the notion of 'entity' is left ambiguous given nine possible entity filters.

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

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

The phrase 'optionally scoped to an entity' implies the tool can be used broadly or filtered, but there is no explicit when-to-use guidance, no mention of the alternative (files_get for a single file), and no exclusions. The agent must infer routing from the schema 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?

With no annotations, the description carries the full behavioral burden, and it discloses very little. It does not state permission requirements, file-size or base64 payload limits, what happens if multiple or zero entity IDs are supplied, or whether the attachment is reversible. 'Upload' implies mutation but nothing else is clarified.

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, which is well-sized. It is efficient, though the brevity comes at the cost of the missing attach-target constraint rather than being purely tight writing.

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 nine-parameter mutation tool with no annotations and no output schema, the description is thin. It never explains the mutually-exclusive entity attach parameters, payload constraints, or the shape of the response, leaving gaps the structured fields do not cover.

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 all nine parameters (org_id, deal_id, lead_id, person_id, product_id, activity_id, file_name, mime_type, content_base64) are already documented in the schema. The description adds no syntax, format, or selection guidance beyond that, so the baseline 3 applies.

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

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

The description states a specific verb ('Upload') and resource ('base64-encoded file') plus the effect ('attach to an entity'), which is more than a restatement of the name. It does not, however, distinguish this tool from the sibling file tools (pipedrive_files_get, pipedrive_files_list) beyond what the name already implies.

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 alternatives, and no indication of the key operational constraint: that the caller must pick exactly one of the eight entity parameters to attach to. The agent is left to infer the attach-target rule 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. 'Get' implies a read-only operation, which is appropriate, but no further behavior (e.g., error handling, permission requirements) is described. The minimal disclosure is acceptable for a simple read but lacks depth.

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, concise sentence that communicates the essential information without any unnecessary words. It is front-loaded and 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?

Given the tool has one parameter, no output schema, and simple behavior, the description is nearly complete. It could optionally mention what a 'filter definition' contains or the response format, but the lack is not critical for a straightforward get operation.

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

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

The input schema has 100% coverage (filter_id is described). The description adds no additional meaning beyond the schema; it only references 'by ID'. Hence, the description does not augment the schema, meeting the baseline of 3.

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

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

The description 'Get a single filter definition by ID.' clearly states the action (get) and resource (filter definition). Among siblings like pipedrive_filters_list and pipedrive_filters_results, this tool is distinctively for retrieving a single definition by ID, making its purpose unambiguous.

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

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

No usage context is provided. The description does not specify when to use this tool over alternatives like pipedrive_filters_list or pipedrive_filters_results, nor does it mention prerequisites or edge cases (e.g., handling missing IDs).

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. The verb 'List' conveys a non-destructive read, but nothing is said about pagination, result limits, or auth requirements. For a trivial read-only listing tool this is acceptable but thin.

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 the optional modifier trailing. No filler, 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 one-optional-parameter list tool with no output schema and no annotations, the description covers the essentials: what is listed and the optional narrowing dimension. It could note that results include filter definitions/metadata, but little is genuinely missing.

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

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

Schema description coverage is 100% and the single 'type' parameter already documents its enum values, so the schema does the heavy lifting. The description restates the parameter's purpose ('by entity type') without adding format or default behavior beyond what the schema shows.

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 clear verb+resource ('List all saved filters') and adds the optional scoping dimension ('by entity type'). It does not, however, distinguish itself from the close siblings pipedrive_filters_get (single filter) or pipedrive_filters_results (filter output), which an agent must infer from naming 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?

'Optionally by entity type' implies when the type parameter is useful, which is a reasonable usage hint. There is no explicit guidance on when to choose this over pipedrive_filters_get or pipedrive_filters_results, so usage is only implied.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose pagination behavior (a genuine trait, backed by the cursor parameter), and 'run a saved filter and return' implies a read-only operation, but it says nothing about permissions, rate limits, or invalid-filter handling.

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 purpose and pagination note both earn their place. It is efficient, though arguably too terse to be maximally helpful for a six-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?

There is no output schema and no annotations, so the description is the only source for behavioral context, and it explains only pagination and the general return ('matching entities'). The schema fully covers inputs, so the gap is mainly around the return shape and prerequisites, which is a moderate but not severe omission.

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

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

Schema description coverage is 100%, so the schema already documents all six parameters including limits, cursor, sort fields, and the entity_type enum. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description states a specific verb ('Run') and resource ('a saved filter') and clarifies the outcome ('return matching entities with pagination'). It is clear what the tool does, but it does not differentiate itself from sibling list tools (pipedrive_deals_list, pipedrive_persons_list) which can return the same entity types.

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 when-to-use guidance, no mention of when to prefer this over direct list tools, and no stated prerequisite that a filter_id must first be obtained (e.g., from pipedrive_filters_list). The saved-filter framing implies a workflow but leaves the agent to infer it.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It discloses only the person/organization constraint; it omits permission requirements, whether a duplicate/conflicting lead is rejected, and what side effects creation triggers. That single constraint is useful but far from adequate for an unannotated 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?

Two short sentences, zero filler, with the core action front-loaded and the key constraint immediately after. Every clause earns its place.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description is thin: it covers the operation and one precondition but says nothing about side effects, permissions, or failure modes. The rich 100% schema coverage compensates for parameter-level gaps, landing it at minimum-viable rather than 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 100%, so the schema already documents all 8 parameters, establishing a baseline of 3. The description adds the cross-parameter constraint that at least one of person_id or organization_id must be supplied, which is genuine value the schema does not express, keeping it at the baseline rather than below it.

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

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

The description opens with a specific verb+resource ("Create a new lead") that an agent can distinguish from siblings such as pipedrive_leads_update, pipedrive_leads_delete, and pipedrive_leads_get by name. It does not explicitly state how it differs from leads_search or other create tools, but the resource and operation are 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 second sentence gives a meaningful precondition ("Requires at least person_id or organization_id"), which is genuine usage guidance. However, there is no explicit when-to-use vs alternatives routing (e.g., leads vs deals) and no when-not-to-use guidance, so it remains implied rather than directive.

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 this is a destructive operation requiring explicit confirmation ('DELETE') and supports a dry-run preview. However, it omits critical behavioral context such as irreversibility, required permissions, and side effects on related records.

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

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

The description is three short sentences, front-loads the core action ('Delete a lead'), and contains no filler. Each sentence contributes useful safety information without redundancy or verbosity.

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

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

For a destructive tool with no annotations and no output schema, the description covers the confirmation requirement and dry-run option but does not explain whether deletion is permanent, what happens to associated data, or what permissions are needed. It is minimally adequate but has clear gaps for a delete operation.

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

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

Schema description coverage is 100%, so the schema already fully documents all four parameters. The description repeats the confirm and dry_run requirements but adds no additional syntax or meaning beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a specific verb and resource: 'Delete a lead.' This distinguishes it from sibling read/create/update operations by action, though it does not explicitly name or contrast with siblings like pipedrive_leads_get or pipedrive_leads_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?

No guidance is provided on when to use this tool versus alternatives, nor are any exclusions or prerequisites beyond the confirmation requirement mentioned. The confirmation string is a parameter constraint, 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 provided, so description must carry behavioral info. Only states 'get' implying read-only, but no mention of error handling (e.g., missing ID), permissions, or response 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?

Single sentence with essential information. 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 one-parameter read tool, the description is minimally adequate. However, it lacks details about return values or error conditions, which would improve completeness.

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 describes lead_id as UUID format and required. Description adds no extra meaning beyond 'by ID'. Schema coverage is 100%, so 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?

Clear verb 'get' and resource 'single lead' with explicit identifier 'by ID'. Distinct from sibling tools like pipedrive_leads_list and pipedrive_leads_search.

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

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

No explicit guidance on when to use this tool versus alternatives. The use case is straightforward (fetching by ID), but no context about prerequisites or conditions.

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

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

With no annotations, the description carries the full behavioral burden. It implies a read-only listing operation and discloses pagination support, but omits auth needs, rate limits, whether all leads are returned, and return format details.

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 very terse, but under-specification is penalized in other dimensions; structurally it is appropriately 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 an 8-parameter list tool with many siblings and no output schema, the description is minimally adequate because the schema fully documents the filtering and pagination options. However, it does not help the agent choose between list/search/get or understand return behavior, leaving 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 100%, so all 8 parameters are already documented in the input schema. The description only mentions filters and pagination generically and adds no syntax, defaults, or semantics beyond the schema.

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

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

The description states a clear verb ('List') and resource ('leads'), plus scope ('with filters and pagination'). It does not differentiate this from sibling tools like pipedrive_leads_search or pipedrive_leads_get, but the core 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?

There is no guidance on when to use this tool versus alternatives such as pipedrive_leads_search, pipedrive_leads_get, or other list tools. No prerequisites or exclusions are provided, leaving selection 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 provided, so the description carries the full behavioral burden, and it does very little. It notes the v2 search API as an implementation detail but says nothing about pagination behavior, result shape, matching semantics, or whether searches are eventually consistent, all of which matter for a search 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 front-loaded sentence with no filler; it is efficient. It is arguably under-specified rather than over-long, but as pure structure 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?

For an 8-parameter search tool with no annotations, no output schema, and only 50% schema coverage, this one-liner leaves far too much for the agent to infer. It should at minimum describe pagination and what a result contains.

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% across 8 parameters, so the description needs to compensate and does not. It never mentions limit, cursor, exact_match, fields, person_id, organization_id, or include_fields, leaving half the parameter surface undocumented in both the schema and the prose.

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

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

States a specific verb+resource (search leads) plus the backing API version, which cleanly distinguishes it from sibling pipedrive_leads_list and pipedrive_leads_get. However, it does not differentiate the search scope from other *_search siblings (deals_search, persons_search), which a fuller description might address.

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 alternatives (e.g., leads_list for browsing vs. this for term matching), and no 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 provided, the description carries the full behavioral burden, yet it discloses nothing beyond the bare mutation. It does not say whether this is a partial update (omitted fields left unchanged) or a full replace, what permissions are required, or what the response looks like. This is a significant gap for a mutation tool with zero annotation coverage.

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

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

The single sentence is front-loaded and free of padding, which is good, but for a 9-parameter tool with a nested object it is under-specified rather than appropriately concise. Brevity here reflects missing information, not disciplined editing.

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 9 parameters, a nested object, no annotations, no output schema, and only 33% schema description coverage, a five-word description leaves an agent without nearly everything it needs to call the tool correctly.

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

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

Schema description coverage is only 33% (lead_id, owner_id, visible_to are documented; title, value, label_ids, person_id, organization_id, expected_close_date are not), and the description adds no parameter meaning at all. It fails to compensate for the coverage gap, especially for the nested value object with amount/currency.

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 (lead), so the operation is unambiguous. However, it does nothing to distinguish itself from siblings like pipedrive_leads_create, pipedrive_leads_delete, or pipedrive_leads_get, which all operate on the same 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?

The description gives no indication of when to use this tool versus alternatives (e.g., leads_get for reading, leads_create for new records) and states no prerequisites such as required permissions or the need for an existing lead_id. 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 behavioral burden. It reveals only that the body is excluded unless include_body is set, which the schema already states via the default and parameter description; nothing is said about permissions, response shape, or error behavior for a missing/invalid ID.

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, zero filler, with the core purpose front-loaded before the optional-parameter note. 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 simple two-parameter read of a single record with fully documented params, the description is essentially sufficient to call the tool correctly. The lack of any mention of required permissions or missing-ID behavior is a minor gap given no annotations and no output schema exist.

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

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

Schema description coverage is 100%, so the schema already explains both parameters, and the baseline is 3. The description's phrasing ('full content') adds a small amount of meaning about what include_body actually returns, but no syntax or format detail beyond the schema.

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

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

States a specific verb ('Get') and resource ('a single mail message') with identifying scope ('by ID'), so the agent can distinguish it from list-style siblings like pipedrive_mail_thread_messages_list. It does not name or differentiate against those siblings explicitly, which keeps 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?

The second sentence gives concrete guidance on using include_body to control payload size, which is genuine usage advice. However, there is no indication of when to use this tool versus the thread or message-list siblings, so the routing guidance is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. 'List' implies a read operation, but the description omits pagination behavior, return cardinality/ordering, and permission requirements. Only the include_body toggle is touched on, leaving most behavioral traits undisclosed.

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 no filler. It is appropriately sized for a simple two-parameter list tool, though the second sentence is more parameter hint than distinct value.

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

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

For a low-complexity list tool this is minimally adequate, but with no annotations and no output schema the description could usefully state read-only nature and pagination expectations. It covers the essentials but leaves real gaps for an agent.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces include_body's role but adds no format or syntax detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

States a specific verb and resource: 'List messages within a mail thread.' An agent can understand the operation clearly. However, it does not differentiate itself from siblings like pipedrive_mail_threads_get or pipedrive_mail_messages_get, leaving the scope boundary implicit.

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 offers no when-to-use context, no prerequisites (e.g., needing a thread ID from mail_threads_list), and no alternatives. The second sentence addresses a parameter rather than usage routing, so there is essentially no 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 surfaces the destructive-confirmation gate and dry_run preview, which is useful, but both are already spelled out in the schema descriptions, so it adds little beyond structured data. It never says deletion is irreversible or whether thread messages cascade-delete.

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 action, then the safety requirement, then the optional mode. 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 mutation tool with no annotations and no output schema, the description covers the confirmation mechanism but omits consequences (irreversibility, cascade to messages) and what dry_run output looks like. Minimum viable 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 100%: thread_id, confirm (const DELETE), dry_run, and reason are all documented in the schema. The description adds no syntax or format detail beyond that, 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?

Clear specific verb+resource: 'Delete a mail thread.' An agent can immediately tell it apart from pipedrive_mail_threads_get, _list, _update, and _mail_thread_messages_list. It does not explicitly name sibling alternatives, 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?

States the operational precondition (confirm: "DELETE") and the dry_run option, which implies usage, but gives no guidance on when to delete vs. archive/update a thread or any consequences/exclusions. Adequate but leaves alternatives unaddressed.

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

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

No annotations are provided, so the description carries the burden. It states 'full details' but does not specify what those details encompass (e.g., messages, participants, subject). However, for a simple GET operation, it is sufficient to indicate a read-only action with no 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?

Single, concise sentence with no fluff. The core information is front-loaded: 'Get a single mail thread by ID' immediately conveys the tool's 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 simple retrieval with one parameter and no output schema, the description is nearly complete. It could mention the response includes the thread's messages or metadata, but that is implied by 'mail thread' context. Minor gap in explaining 'full 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 coverage is 100% for the single parameter thread_id. The description adds 'by ID with full details', which aligns with the schema but does not provide additional semantic meaning beyond what the schema already offers ('The mail thread ID to retrieve'). Baseline 3 is appropriate.

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

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

The description clearly states the action (Get), the resource (single mail thread), the identifier (by ID), and the scope (full details). It distinguishes from sibling tools like pipedrive_mail_threads_list which returns multiple threads, and pipedrive_mail_threads_delete which modifies.

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

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

No explicit guidance on when to use vs alternatives. It implies usage for retrieving a specific thread, but does not mention that pipedrive_mail_threads_list should be used for browsing, or that pipedrive_mail_thread_messages_list can retrieve messages within a thread.

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 operation but says nothing about pagination behavior, what happens when the folder is empty, ordering, or authentication. For a list tool with zero annotation coverage this leaves real 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?

A single front-loaded sentence with zero waste; the scope and optional filter 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 simple read-only list tool whose parameters are fully documented by the schema, the description is minimally adequate. It lacks pagination/return context and any routing to related mail tools, but no output schema means the description isn't expected to explain returns.

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 echoes the folder enum values but adds no syntax or behavior beyond the schema (e.g., default inbox is already documented in the schema).

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

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

States a specific verb (List) and resource (mail threads) with the folder filter scope. It distinguishes itself from mail_threads_get/update/delete by the read-list nature, though it doesn't explicitly name those siblings. Clear but not maximally differentiated.

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

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

No when-to-use guidance. It doesn't say when to prefer this over pipedrive_mail_threads_get (single thread) or pipedrive_mail_thread_messages_list, nor how to page through results. Usage is only implied by the verb '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?

No annotations are provided, so the description carries the full behavioral burden. It says 'update' and lists fields, but does not disclose whether linking to a deal/lead replaces or adds to existing links, whether archiving or sharing is reversible, what permissions are required, or what side effects the call has.

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 verb and resource front-loaded, followed by the affected fields. No filler, though it is arguably terse to the point of omitting useful context rather than being optimally structured.

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

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

For a six-parameter mutation tool with no annotations and no output schema, the description covers the mutation surface but omits permissions, reversibility, and combined-call behavior. The 100% schema coverage compensates for the parameter side, making this minimally adequate rather than 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 100% and every one of the six parameters has an inline description, so the schema does the heavy lifting and the baseline is 3. The description's field list roughly mirrors the schema (deal/lead link, read/unread, archive, share) without adding syntax, constraints, or interaction rules beyond it.

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 (mail thread) and enumerates the four distinct mutation surfaces: deal/lead linking, read state, archive state, sharing. An agent can immediately tell this apart from the sibling read tools (mail_threads_get, mail_threads_list, mail_messages_get). It does not explicitly name the siblings it is not, so it stops short of a 5.

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

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

There is no guidance on when to use this versus pipedrive_mail_threads_get or pipedrive_mail_threads_delete, no prerequisites, and no indication of whether all four operations can be combined in one call. The agent is left to 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 disclosure burden. It usefully reveals the default identity binding (token owner) and the shared-token scenario, but says nothing about permissions required, failure behavior when as_user does not resolve, or rate limits.

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, zero filler, with the identity default stated before the override option. 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 one-optional-param read tool with no output schema, the description covers the essential decision (default identity vs. impersonation) and the shared-token context. The remaining gaps, resolution failures and permissions, are minor.

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

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

Schema description coverage is 100% and the single parameter is fully documented there, so the baseline is 3. The description's 'by name or email' restates the schema's accepted formats without adding syntax, matching rules, or error 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 specific verb and resource ('Show the current Pipedrive user') plus the scope qualifier '(API token owner)', which cleanly separates it from the sibling user tools (pipedrive_users_get, pipedrive_users_list) that require an explicit identifier. An agent can pick this tool 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 positive routing rule: use as_user to resolve a different team member by name or email. It does not state a when-not-to-use case (e.g., use users_get when you already have an ID), but the implied default-vs-override decision is clear enough to act on.

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

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

No annotations are provided, so the description carries the burden. 'List' and 'open deals' imply a read-only, filtered query, and the sort order ('most recently updated') is disclosed, but there is no mention of pagination behavior, what 'open' excludes, or permission/auth needs beyond the as_user note.

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

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

Two compact sentences, front-loaded with the core scope before the ordering detail. No waste.

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 list tool with no output schema and no annotations, the description covers scope and ordering but omits what fields are returned and how pagination is expected to be used, which the agent must infer from 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 100% with all four parameters documented in the schema itself. The description only gestures at as_user via '(or as_user)' and adds nothing about pipeline_id or cursoring beyond what the schema already says, so baseline 3 is appropriate.

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

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

States a specific verb (List), resource (open deals), and scope (owned by current user or as_user), plus ordering. It implicitly separates itself from pipedrive_deals_list by the 'owned by current user' restriction, though it never names that sibling to sharpen the distinction.

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

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

Usage is implied: call this when you want the caller's own open deals rather than all deals. There is no explicit when-to-use/when-not guidance and no reference to pipedrive_deals_list or pipedrive_deals_search as alternatives.

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 present, so the description carries the full burden. 'Show' implies a read-only operation and the scope is well stated, but there is no disclosure of permissions needed, rate limits, whether 'done' is based on a specific status field, or how paging behaves beyond what the schema params say.

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 core filter and the user-scope caveat front-loaded. No filler, nothing 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 a no-required-param list tool with three fully documented parameters and no output schema, the description is nearly sufficient. It could mention the shape of returned activities or pagination behavior, but no critical calling information is missing.

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

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

Schema description coverage is 100%, so limit and cursor are fully documented in the schema. The description echoes the 'as_user' concept ('or as_user'), adding a small amount of context but no syntax or semantics beyond the schema; baseline 3 applies.

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

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

States a specific verb (Show) and resource (activities) plus two sharp scope qualifiers: 'past due' and 'not yet done' for the current user. That combination clearly separates it from sibling pipedrive_my_upcoming_activities and pipedrive_activities_list, though no sibling is named.

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 filter conditions ('past due and not yet done') imply when the tool is useful, and the 'as_user' aside hints at the shared-token scenario. However, it never explicitly contrasts with the nearby siblings (my_upcoming_activities, activities_list), leaving the agent to infer the routing.

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

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

With no annotations provided, the description carries the full behavioral burden. It does disclose the output nature (aggregated deal counts and values by stage), which is useful, but it omits any safety profile, permissions needed, or whether the operation is read-only, leaving gaps for a tool with zero annotation coverage.

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

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

A single, front-loaded sentence that states scope and output with no wasted words. It is efficient, though it crams scope and return content into one clause without further structuring.

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

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

For a read-only, two-parameter summary tool with no output schema, the description adequately conveys what is returned (counts and values by stage) and the user scoping. There is no output schema, so explaining the return content in prose is the right call, and it does so.

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

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

Schema description coverage is 100%, so both parameters (as_user, pipeline_id) are already fully documented in the schema. The description only references them obliquely ('current user (or as_user)', 'by stage') and adds no syntax or default detail beyond the schema, making the baseline 3 appropriate.

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

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

The description names a specific resource (pipeline snapshot) scoped to the current user and states the returned content (deal counts and values by stage). It is clearly distinguishable from generic list tools, though it does not explicitly contrast itself with the sibling pipedrive_deals_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 produces but gives no when-to-use guidance, no conditions for choosing it over siblings like pipedrive_deals_summary or pipedrive_my_open_deals, and no exclusions. The only hint about usage is the parenthetical 'or as_user', which the schema already covers.

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

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

No annotations are provided, so the description carries the full burden. It discloses the default window and the as_user acting behavior, and 'Show' implies a non-mutating read, but it says nothing about pagination behavior, result ordering, or activity types returned. Adequate but thin for an unannotated tool.

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

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

One sentence with zero filler; the time window and user scope are front-loaded before the optional as_user parenthetical. Nothing could be removed without losing information.

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

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

For a read-only list tool with 100% schema coverage and no output schema, the description covers purpose, scope, and the as_user nuance. It omits return-shape hints such as ordering or which activity fields come back, but nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so days, limit, cursor, and as_user are already documented in the schema. The description echoes the days default and the as_user concept without adding syntax or edge-case meaning beyond it, 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?

Specific verb (Show) plus resource (upcoming activities), scoped by time window and user, which implicitly distinguishes it from pipedrive_my_overdue_activities and pipedrive_activities_list. It never names those siblings explicitly, so differentiation is inferred rather than stated.

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

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

The word 'upcoming' implies the use case against the overdue sibling, but there is no explicit when-to-use guidance, no exclusions, and no mention of the generic pipedrive_activities_list alternative. Usage is left 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 provided, so the description carries the full behavioral burden, yet it only discloses the content_html format nuance (no CDATA wrapper). It says nothing about required permissions, what happens on an invalid note_id, whether comments are editable after creation, or rate limits — 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 action front-loaded and the format caveat second. No filler or repetition, though it is on the terse side given what a mutation tool ought to convey.

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 create tool with no annotations and no output schema, the description is too thin. It omits permission requirements, the expected success/error behavior, and any reference to the related update/delete/list sibling tools that an agent would need to reason about the operation.

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

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

Schema description coverage is 100%, with both note_id and content_html well documented, including sanitization and CDATA guidance. The description's note about plain HTML without a CDATA wrapper echoes what the schema already states, so it adds little beyond the baseline.

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

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

States a specific verb and resource: 'Add a comment to a note.' An agent can immediately tell this is the create operation for note comments. It doesn't explicitly contrast with the sibling update/delete/list comment tools, but the name plus verb make the distinction clear 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?

The description gives no when-to-use guidance, no prerequisites, and never names the alternative comment tools (update, delete, list). The only routing signal is the tool name itself, so the agent must infer everything about appropriate 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 carries the full burden. It usefully discloses that this is a guarded destructive operation (confirm must equal "DELETE") and that a dry_run preview exists, which is real behavioral value. However, it says nothing about permanence, required permissions, or what happens if the comment_id is invalid.

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

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

Three short sentences, front-loaded with the action, then the safety gate, then the preview option. Tight and readable, though the dry_run sentence largely duplicates the schema's own description.

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

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

There is no output schema and no annotations, so the description must carry the full context. It covers the critical safety mechanics (confirm, dry_run) but omits irreversibility, error behavior, and return shape, leaving meaningful gaps for a destructive 5-parameter tool.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters including the confirm const and dry_run semantics. The description merely restates confirm and dry_run and adds nothing about note_id, comment_id, or reason, so 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 and resource ("Delete a comment from a note") that is unambiguously distinct from the sibling create/update/list comment tools. It does not explicitly name those siblings, but the operation is clear enough that no agent would confuse them.

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

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

No when-to-use context, no prerequisites, and no mention of alternatives such as update vs delete or the parent note tool. The only conditional guidance is the confirm requirement, which is a safety gate rather than 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, and the description only states the basic action. It does not disclose behavioral traits like read-only nature, required permissions, or error conditions. For a simple get, more transparency could include indicating it does not modify data.

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

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

The description is a single, short sentence that is front-loaded with the key information. No unnecessary words or details, earning its place efficiently.

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

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

For a simple get operation with two required parameters and no output schema, the description is mostly complete. It clearly states what the tool does and the required identifiers. Minor lack of mention that the comment must belong to the note, though implied.

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

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

Schema description coverage is 100% with both parameters described in the input schema. The description adds no extra meaning beyond what the schema already provides, meeting the baseline but not exceeding it.

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

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

The description clearly states the action (Get), the resource (a single comment by UUID), and the context (on a note). This distinguishes it from sibling tools like pipedrive_note_comments_list (list) and the CRUD operations for notes.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it or compare to related tools like list or the note-level 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?

No annotations are provided, so the description carries the full burden and discloses almost nothing: it doesn't state that this is a read-only operation, whether it paginates, what the default page size is, or what happens for an invalid/missing note. One sentence of pure restatement.

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, front-loaded with the verb and resource. It is near-minimal, but well-formed rather than padded.

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

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

For a simple read-only list endpoint with a fully documented 3-parameter schema, this is minimally adequate. Gaps remain: no output schema and no mention of pagination behavior or empty results, which the description could have covered since annotations are absent.

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

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

Schema description coverage is 100%, so limit, cursor, and note_id are already fully documented in the schema (default 25, max 100, opaque token, note ID). The description adds no parameter meaning beyond that, making the baseline 3 appropriate.

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

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

Specific verb 'List' plus resource 'comments on a note' — an agent can immediately tell what it retrieves. It does not explicitly distinguish itself from the sibling pipedrive_note_comments_get (singular fetch), though the plural 'comments' implies a collection.

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 pipedrive_note_comments_get, nor prerequisites like needing a valid note_id or how paging should be driven. The reader must infer everything from the name and schema.

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 adds one genuinely useful behavioral detail about the content_html payload format (no CDATA), but says nothing about permissions/ownership, whether the update fully replaces existing content, or what happens on invalid comment_id. Partial disclosure for a mutation tool.

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

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

Two short, front-loaded sentences with the core action first. The second sentence duplicates what the content_html schema description already states, so it is slightly redundant rather than purely additive.

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?

Parameters are fully documented in the schema, so the description needn't re-explain them. However, for a no-annotation, no-output-schema mutation tool it omits mutation semantics (replacement behavior, permissions, error cases), leaving the agent with a minimally viable picture.

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

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

Schema coverage is 100% and the schema's own content_html description already covers the plain-HTML/CDATA guidance, so the description largely restates structured data rather than adding meaning. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Update a comment on a note'), which cleanly distinguishes it from the create/delete/get/list comment siblings by verb alone. It stops short of explicitly naming those siblings or clarifying scope (e.g. that it only replaces content, not author/timestamps).

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: nothing says when to update an existing comment versus creating a new one, nor any prerequisite such as needing the comment_id from a prior list/get call. Usage is only implied by the tool name.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose a genuine input-handling trait (HTML passed directly, no CDATA wrapper), but says nothing about permissions, whether undirected notes are allowed, or what is returned on success.

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 purpose before the format caveat. Efficient, though the second sentence partially duplicates what the content_html schema property already says.

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 eight-parameter mutation tool with 63% schema coverage, no annotations, and no output schema needs more context than two sentences provide. The pinned_* flags and the implicit requirement of at least one attach target are left 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 63%, so the schema already documents most parameters, including an extensive content_html description. The description's CDATA caveat mostly restates that schema text, and it adds nothing about the three pinned_* flags or the attach-target 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 specific verb (Create) and resource (a note) plus the four entity types it can attach to, which is enough for an agent to distinguish it from pipedrive_notes_list, pipedrive_notes_update, and pipedrive_note_comments_create. It does not explicitly contrast itself with those siblings, but the scope is unambiguous.

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

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

No guidance on when to create a note versus a note comment versus an activity, and no prerequisites are stated. Critically, the description never says that at least one of deal_id/person_id/org_id/lead_id is needed for the note to be useful, even though none of them appear in the required 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?

No annotations are provided, so the description carries the full behavioral burden. It flags the confirmation gate, but that is already stated in the schema's const and dry_run descriptions, and it omits the essentials for a destructive operation: irreversibility, permission requirements, and side effects such as what happens to attached note comments.

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

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

Three terse sentences, front-loaded with the verb and resource, then the safety requirements. Every sentence carries information and there is no filler.

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

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

For a destructive mutation with zero annotations and no output schema, the description is too thin. It never states that deletion is permanent, whether a dry_run preview has any cost, or that the reason field is accepted, leaving the agent without the context needed to call this safely.

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

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

Schema description coverage is 100%, so note_id, confirm, reason, and dry_run are all documented in the schema itself. The description repeats confirm and dry_run without adding format, constraint, or edge-case 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 and resource ('Delete a note'), which an agent can distinguish from pipedrive_notes_get/update/list by name. It does not explicitly name or contrast with a sibling, 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 procedural requirements (confirm must be "DELETE", dry_run available) but no when-to-use guidance, no prerequisites, and no mention of alternatives for removing note content. Nothing tells the agent under what circumstances deletion is appropriate.

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

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

No annotations are provided, so the description must convey behavioral traits. It indicates a read operation but does not disclose error handling, permission requirements, or scope beyond retrieving a single note by ID. Adequate but could be richer.

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 that conveys the core action and required parameter. No fluff or unnecessary 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 get-by-ID tool with one parameter and no output schema, the description provides sufficient context. It does not mention return format or error scenarios, but given the low complexity, it is mostly complete.

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

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

The description adds minimal meaning beyond the input schema: 'by ID' is already implied by the parameter description 'The note ID to retrieve'. With 100% schema coverage, baseline is 3; no additional parameter insights provided.

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

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

The description clearly states the tool retrieves a single note by its ID. It uses specific verb 'Get' and resource 'single note', which distinguishes it from sibling tools like list, create, update, and delete.

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