Pipedrive MCP by usefulapi

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

Annotations only supply destructiveHint=true, so the description carries most of the burden. It adds real context by disclosing the API generation ('Uses v1, v2 has no notes endpoint') and the REST endpoint, which explains why the call behaves as it does. It says nothing about permissions, failure modes, or what mutating a linked entity implies, and does not reconcile the destructiveHint=true annotation with an additive 'add' operation.

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

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

Three short sentences, zero filler, with the core purpose and linking constraint front-loaded before the implementation notes. Every sentence carries either a constraint or an implementation fact an agent needs.

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

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

For a simple single-object create tool with no output schema and thin annotations, the description covers required input, the link constraint, and the API version quirk. Its only meaningful gap is the return shape (e.g. the created note id), which nothing else in the definition supplies.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds semantics the schema does not encode: only `content` is required and at least one link id must be supplied, a constraint invisible in the schema's required list. It also confirms `content` accepts HTML or plain text, matching but reinforcing the schema.

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

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

States a specific verb and resource ('Add a note') plus the binding constraint that it must link to at least one deal/person/organization/lead, which genuinely narrows what the call means. It does not name the counterpart sibling (pipedrive_list_notes) or distinguish itself from pipedrive_create_activity, so sibling separation is only 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?

'linked to at least one of a deal/person/organization/lead' functions as an eligibility rule for when the tool applies, and the required `content` is called out. However there is no explicit when-to-use/when-not guidance, no mention of the sibling list_notes or of other creation tools (create_activity, create_deal), leaving the agent to infer 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?

Annotations only declare destructiveHint=true, so the bar is lower, and the description does add the underlying REST operation (POST /api/v2/activities) plus the required-field constraint. It discloses nothing about permissions, side effects on linked entities, or whether the created record is returned, so it is only marginally additive.

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 with the core purpose front-loaded and no filler. The endpoint sentence is the only borderline element, but it is compact and gives an agent a useful anchor to the API 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?

With 11 parameters and no output schema, the description covers the call adequately but omits what the call returns (e.g., the new activity id needed for follow-up operations). It is sufficient to invoke the tool but leaves a gap an agent creating a linked workflow would notice.

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 11 parameters, so the schema already carries the semantics. The description lightly groups parameters (linkage fields, type/date/time) and restates that subject is required, which is duplicative rather than additive. 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 ('Create a new activity (task/event)') and clarifies the ambiguity of 'activity' with the parenthetical, which separates it from siblings like pipedrive_add_note or pipedrive_create_deal. It does not explicitly name a sibling to contrast against, 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 line 'link it to a deal/person/org and set type/date/time as needed' implies when the linking fields matter, but gives no guidance on when to create an activity versus adding a note or creating a related entity. Usage is inferable but not 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?

Annotations already supply destructiveHint=true, so the safety profile is partly covered. The description adds the underlying REST endpoint, which is useful context, but says nothing about permissions, what happens with invalid linked ids, or the fact that a new deal id is returned for chaining. No contradiction with the annotation.

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

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

Two compact sentences plus the endpoint, with the required field front-loaded. Minor redundancy in repeating that `title` is required, which the schema already enforces, but nothing bloated.

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

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

For an 11-parameter mutation tool with no output schema, the description is thin: it does not describe the created object's return (id) that an agent needs to chain follow-up calls, nor pipeline/stage/visibility semantics. Adequate to invoke, but incomplete for a create 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 every parameter is already documented. The description only restates that `title` is required and lists the linkable entities already present in the schema, adding no format or interaction detail (e.g., currency pairing with value). 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+resource ("Create a new deal") and identifies the required field, which is enough to separate it from create_person/create_activity/create_note siblings. It does not explicitly name an alternative, 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?

"link it to a person/org/pipeline/stage/owner as needed" implies the tool is for creating deals with optional associations, but there is no when-to-use vs which-sibling guidance or prerequisites (e.g., needing existing person/org ids). Usage must be inferred.

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

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

Annotations only provide destructiveHint=true and a title; the description adds meaningful context beyond that by disclosing required field ('name is required') and the mapping behavior for email/phone (convenience strings mapped to structured arrays). It does not mention permissions, duplicate handling, or return format, but the mapping disclosure is substantive extra value.

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: purpose first, then required-field and mapping details, then the REST endpoint. No filler; every clause earns its place.

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

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

For a 6-param create tool with no output schema, the description covers the required field, the non-obvious mapping behavior, and the endpoint. It omits duplicate-handling guidance and what the response returns, but is largely complete for correct invocation.

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 six parameters. The description adds the useful mapping semantics for email/phone (convenience strings -> structured arrays), which is not obvious from the schema, but adds nothing for org_id/owner_id/visible_to. Baseline 3 with slight added value.

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 person (contact)') and disambiguates the resource with the parenthetical 'contact'. Clearly distinguishable from siblings like create_deal, create_activity, and add_note.

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

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

Implies usage (creating a contact) but gives no when-to-use vs alternatives such as search_persons (to check for duplicates first) or get_person. No exclusions or prerequisites 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?

Annotations already declare readOnlyHint=true, so safety is covered; the description adds value beyond that by naming the concrete REST endpoint (GET /api/v1/users/me) and listing the returned fields. It does not discuss auth failure behavior or rate limits, but for a zero-parameter read that is a minor omission.

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 zero filler; the purpose and payload are front-loaded, and the endpoint reference sits at the end where it belongs. Every clause adds information.

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

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

Because no output schema exists, the description must carry the return shape, and it does so by enumerating name, email, company, locale, and timezone. Combined with the annotations, an agent has enough to call this correctly; only edge-case behavior (unauthenticated or invalid token) is 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?

The tool takes no parameters and the schema is empty, so per the baseline there is nothing the description needs to compensate for. It correctly refrains from inventing parameters, and the 'authenticated user' framing implicitly clarifies that identity comes from the session rather than an argument.

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 the authenticated user's profile') and enumerates the returned fields, so the agent knows exactly what it does. It is also clearly distinct from every sibling, which all cover deals, persons, organizations, notes, or 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?

The description makes the context of use unambiguous by scoping it to the 'authenticated user', and no sibling competes for that target, so no explicit alternative needs to be named. It stops short of saying when-not to call it (e.g., before onboarding or when no API token is configured), which keeps it out of the top band.

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

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

The readOnlyHint annotation already declares the safe read-only nature, and the description adds nothing behavioral beyond that – no mention of behavior when the id is missing or not found, or permission requirements. The REST path note locates the operation but is not a behavioral trait.

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 purpose first. The trailing REST endpoint line is mildly redundant for an agent but costs little.

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-parameter getter this is close to sufficient, but with no output schema the description gives no hint of the returned deal shape, and it omits what happens on a bad or missing id.

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 'id' parameter is fully documented in the schema. The description's 'by its id' merely confirms the schema, adding no format or range detail, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Get a single deal by its id'), and the word 'single' implicitly separates it from list_deals and search_deals siblings. 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?

Usage is implied by 'single deal by its id' – fetch one record when you already have the id – but there is no explicit statement of when to prefer this over list_deals or search_deals, nor any prerequisite or failure 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?

readOnlyHint=true already declares this is a safe read, so the bar is lower. The description adds the REST endpoint mapping (GET /api/v2/organizations/{id}), which is useful orientation but not behavioral detail such as not-found/error handling or response shape.

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

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

Two short sentences with the core purpose front-loaded and no wasted wording. The REST endpoint line is optional but compact and informative.

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

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

For a single-parameter read tool whose read-only safety is covered by annotations and whose parameter is fully documented, the description is essentially complete. No output schema exists, but return-value explanation is not required.

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 single 'id' parameter is already documented in the schema as required. The description's 'by its id' adds no format or type detail 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 and resource ('Get a single organization') and scopes it to retrieval by id, which distinguishes it from the list/search siblings. It does not name the alternatives explicitly, but the 'single...by its id' phrasing makes the retrieval semantics unambiguous.

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

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

Usage is implied by 'by its id' - an agent can infer this is the point-lookup versus list/search - but there is no explicit when-to-use or when-not-to-use guidance naming siblings like pipedrive_list_organizations or pipedrive_search_organizations.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the concrete endpoint (GET /api/v2/persons/{id}), which is modest extra context, but says nothing about not-found behavior, permissions, or response shape.

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

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

Two short sentences, front-loaded with the operation and followed by the endpoint mapping. 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 trivial one-parameter read tool with annotations covering the safety profile and a fully documented schema, the definition is essentially complete. Only a brief note on not-found handling or return shape would improve it, and no output schema exists to cover that.

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

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

Schema description coverage is 100% and the single id parameter is fully documented in the schema as required. The description only restates 'by its id', adding no format, range, or sourcing guidance beyond what the schema already provides, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get a single person (contact) by its id') plus the underlying REST endpoint, so the operation is unambiguous. It does not, however, explicitly distinguish itself from the sibling read paths pipedrive_list_persons or pipedrive_search_persons.

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 'by its id' implies the precondition for use (you must already have a person id) and indirectly routes id-less lookups elsewhere. There is no explicit statement of when to prefer this over list_persons/search_persons or what to do if the id is unknown.

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?

readOnlyHint=true already tells the agent this is a safe read, so the description is not the sole carrier of behavior. It adds the underlying REST endpoint (GET /api/v2/activities), but says nothing about pagination, rate limits, or result shape for what is clearly a paginated list endpoint.

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

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

Two compact sentences with the core purpose front-loaded and no filler. The REST endpoint clause is mildly redundant for an agent but is short and does ground the operation.

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

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

With 100% schema coverage and readOnlyHint, the description is close to sufficient, but for a cursor-paginated list with no output schema it never mentions that results paginate or how to continue. An agent must infer pagination purely from the schema's cursor field.

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 including limit, cursor and updated_since are fully documented in the schema. The description merely re-enumerates the filter names, adding no syntax, defaults, or combination semantics beyond the schema — the baseline of 3 applies.

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

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

States a specific verb and resource ('List activities') and disambiguates the domain term by parenthesizing '(tasks/events)'. It does not explicitly distinguish itself from siblings like pipedrive_list_deals, but those cover different resources so overlap risk is low.

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?

Says the list is 'optionally filtered by filter/owner/deal/person/org/done/updated_since', which implies when each filter applies, but there is no explicit guidance on when to use this versus search tools or which filters combine. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data. The description adds the underlying REST call (GET /api/v2/deals), which is mildly useful, but says nothing about pagination behaviour, result ordering defaults, or rate limits despite a cursor-based pagination parameter being present.

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

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

Two compact sentences with the core purpose front-loaded and no filler. The filter enumeration is somewhat redundant against a 100%-documented schema, which is the only thing keeping this from a 5.

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 11 fully documented optional parameters, a read-only annotation, and no output schema to explain, the description covers what an agent needs to invoke the call. The remaining gap is sibling routing (search_deals vs list_deals), which is a minor omission for a straightforward list 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 all 11 parameters (including limit bounds and cursor semantics) are already documented in the schema. The description's filter list merely mirrors those field names and adds no syntax, default, or format detail beyond the schema; baseline 3 applies.

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

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

States a specific verb and resource ('List deals') and enumerates the supported filter axes plus sorting, so the agent knows exactly what the tool returns. It does not, however, differentiate itself from the sibling pipedrive_search_deals, leaving that routing decision 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?

'Optionally filtered by filter/owner/person/org/pipeline/stage/status and sorted' implies the intended usage pattern, but there is no explicit when-to-use or when-not-to-use guidance, and no pointer to pipedrive_search_deals for text queries. Usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, so safety is covered; the description usefully adds that it targets the v1 REST API (GET /api/v1/notes) and that pagination is start+limit rather than cursor-based. It still doesn't say anything about result ordering defaults or total-count behavior, keeping it short of a 5.

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

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

Three tight sentences: purpose and filters first, then the API-version constraint and pagination scheme, then the raw endpoint. Every sentence carries distinct information and nothing is padded.

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

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

For a read-only list tool with a fully documented schema and no output schema, the description covers what is needed to call it correctly: filters, pagination style, and API version. Return-shape details are exempt given no output schema, though a hint about default sort order would have made it 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 all eight parameters (including sort, limit, start, and the id filters) are already documented; the description only restates the filterable entity set. It adds no format or default detail beyond the schema, which is the expected 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?

States a specific verb+resource ('List notes') plus the exact filter dimensions available (user/deal/person/org/lead), so an agent knows what it retrieves. It does not explicitly name pipedrive_add_note as the write counterpart, but the List/Add verb split makes the distinction obvious without opening schemas.

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

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

Usage is implied by the optional filters, and the note that v2 has no notes endpoint explains why this specific tool/API version must be used. However, there is no explicit when-to-use guidance or exclusion (e.g., when to prefer search_items for note lookup).

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

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

Annotations already declare readOnlyHint=true, so safety is covered structurally. The description usefully adds the exact REST endpoint and notes filtering/sorting behavior, but says nothing about pagination behavior or defaults beyond what the cursor and limit schema entries already document.

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

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

Two compact sentences with zero filler, front-loading the capability before the endpoint detail. 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 read-only collection endpoint with all six parameters fully documented in the schema and no output schema, the description is nearly sufficient. A brief note on default page size or ordering would close the last gap.

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

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

Schema coverage is 100% and each parameter already carries a description, so the schema does the heavy lifting. The description's mention of filter/owner/sort merely restates those parameters without adding format, interaction, or default 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 ('List organizations') plus the two filter axes (filter/owner) and sorting, and pins the concrete endpoint GET /api/v2/organizations. It does not explicitly distinguish itself from the sibling search_organizations, but the read/collection framing is unambiguous.

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

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

'optionally filtered by filter/owner and sorted' implies the intended context (browse a collection with light filtering), but there is no explicit when-to-use versus search_organizations when the caller has keywords, nor versus get_organization for a single record. Usage is implied rather than stated.

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

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

readOnlyHint=true already tells the agent this is a non-destructive read, so the bar is lower. The description adds the REST endpoint (GET /api/v2/persons), which is useful orientation, but discloses nothing about pagination behavior or return shape beyond what the schema's cursor field already implies.

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

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

Two tight sentences with zero filler; the capability statement is front-loaded and the REST endpoint is a compact secondary detail. Every clause earns its place.

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

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

With no output schema, the description could note what the listing returns and that responses carry a next_cursor for pagination. As written it is adequate for a simple list tool but leaves the return contract and paging flow to the schema to imply.

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 seven parameters are fully documented by the schema. The description's mention of filter/owner/org/sort merely echoes those parameters without adding format or constraint detail, 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 (persons/contacts) and enumerates the filtering/sorting surfaces. It implicitly separates from get_person/create_person by being a list operation, but it never names the close sibling search_persons, so an agent must infer the list-vs-search 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?

The phrase 'optionally filtered by filter/owner/org and sorted' gives implied context for when this tool applies, but there is no explicit when-to-use guidance and no mention of search_persons as the 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?

The readOnlyHint annotation already establishes this is a safe read, and the description adds the underlying REST endpoint (GET /api/v2/pipelines). However, it says nothing about pagination behavior, result shape, or default page size, so it adds only modest context beyond the annotation.

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

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

Two terse, front-loaded sentences with no filler; the purpose leads and the endpoint reference follows. The API-endpoint sentence is of marginal value to an agent but is not wasteful.

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

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

For a four-parameter list tool with an annotation covering safety and a fully documented schema, the essentials are present. Still missing is any note on pagination/return behavior for a cursor-paginated endpoint, which an agent would benefit from when chaining calls.

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 clear defaults, enums, and cursor semantics documented in the schema itself. The description contributes nothing about limit, cursor, or sort parameters, 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 all pipelines') that cleanly distinguishes it from write siblings like pipedrive_create_deal. It does not differentiate from the closest sibling, pipedrive_list_stages, nor explain what a 'pipeline' contains, but the verb+resource pair is unambiguous.

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

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

The description gives no when-to-use guidance, no prerequisites, and no mention of alternatives such as pipedrive_list_stages. An agent must infer usage purely from the name.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating read. The description only adds the underlying REST route, which offers little behavioral value beyond the annotation. It says nothing about ordering, what a 'stage' represents, or result shape.

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

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

Two short sentences, front-loaded with the core operation and followed by an optional scope. Every sentence earns its place with no padding.

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

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

For a simple three-parameter, zero-required read tool with annotations declaring read-only and no output schema, the definition is largely sufficient. The one gap is that it never hints at return contents or default paging behavior, but the schema and annotations carry most of the burden.

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 pipeline_id are already fully documented in the schema. The description restates the pipeline restriction but adds no syntax or format detail beyond it, 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?

States a specific verb and resource ('List stages') and adds scope ('optionally restricted to a single pipeline'), so the agent understands exactly what is returned. It does not explicitly contrast with siblings like pipedrive_list_pipelines, but no sibling performs the same function, so the risk of confusion is low.

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 restricted to a single pipeline' implies when to supply pipeline_id, which is useful implied usage. However, there is no explicit when-to-use guidance, no mention of when to prefer pipelines over stages, and no exclusion 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?

The readOnlyHint annotation already establishes this is a safe, non-mutating read. The description adds the REST endpoint reference but says nothing about pagination behavior, result ordering, or how the cursor interacts with limit — details that matter for a search endpoint with 500-result caps.

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 endpoint detail secondary. Nothing is wasted and nothing important is buried.

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

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

With 8 parameters, no output schema, and only a readOnlyHint annotation, the description is thin. The schema carries all parameter detail, but there is no guidance on pagination flow, result shape, or how search differs from listing — leaving the definition 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 every parameter (term, limit, cursor, fields, status, person_id, exact_match, organization_id) is already documented in the schema. The single sentence 'across selected fields' loosely gestures at the fields parameter but adds no meaning beyond what the schema provides. 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 ('Search deals by term across selected fields') and even names the underlying REST endpoint. It is clear what the tool does, but it never contrasts itself with the obvious siblings pipedrive_list_deals or pipedrive_search_items, so an agent must 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?

The description gives no when-to-use guidance, no exclusions, and no mention of alternatives such as pipedrive_list_deals (browse) or pipedrive_search_items (cross-entity search). The agent is left to infer that this is for term-based deal lookup.

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

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

The readOnlyHint annotation already establishes this is a safe read, so the bar is lower. The description adds only the REST mapping (GET /api/v2/itemSearch), which is largely redundant with the annotation, and discloses nothing about rate limits, result caps, or how pagination via next_cursor behaves across mixed item types.

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 capability and with no filler. The trailing REST endpoint reference earns its place only for debugging purposes and is the one element that does not help an agent select or call the tool.

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

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

With seven parameters, a read-only annotation, and no output schema, the description is adequate but thin: it never hints at the shape of the response or how the opaque cursor relates to the returned results, and it does not explain interactions between fields, item_types, and exact_match.

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% — term length, limit bounds/default, cursor provenance, allowed item_types, and exact_match/search_for_related_items semantics are all documented in the schema. The description adds no parameter-level meaning 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 (search) and an explicit scope (global, across deals, persons, organizations, products, leads, files). The word 'global' plus the enumerated item types cleanly distinguishes it from the entity-scoped siblings pipedrive_search_deals, pipedrive_search_persons, and pipedrive_search_organizations.

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 rather than stated: 'global search across multiple item types' suggests this is the tool for cross-type lookups, leaving the entity-specific search siblings as the alternative. However, it never says when to prefer this over pipedrive_search_deals or what happens if item_types is omitted, so the agent must 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?

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the REST endpoint mapping (GET /api/v2/organizations/search) and the fact that the search spans 'selected fields', which is mild extra context. It does not disclose pagination behavior beyond the cursor parameter, nor which fields are searched by default.

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 and followed by the endpoint reference. No filler, no redundancy, and the key scoping fact appears 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 five-parameter read-only search tool with no output schema, the definition plus the fully documented schema covers what an agent needs to call it correctly. The remaining gap is behavioral: no mention of default searched fields or how cursor pagination terminates, which would help for multi-page retrieval.

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 with constraints, defaults, allowed field values, and cursor semantics. The phrase 'across selected fields' loosely points at the 'fields' parameter but adds no detail beyond the schema. 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?

The description gives a specific verb+resource ('Search organizations by term') and clarifies scope ('across selected fields'), which distinguishes it from pipedrive_get_organization and pipedrive_list_organizations. It never names the sibling search tools (pipedrive_search_persons, pipedrive_search_deals, pipedrive_search_items), so differentiation relies on the reader inferring it from the entity name.

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 context, no statement of when to prefer this over pipedrive_list_organizations or the generic pipedrive_search_items, and no prerequisites. The only implied guidance is the presence of a 'term' parameter, which the agent could already read from the 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?

readOnlyHint=true already establishes the safety profile, so the description need not restate it. The description adds the underlying REST endpoint (GET /api/v2/persons/search), which is mild but genuine context; however it says nothing about result caps, pagination behavior, or how cursor-based traversal works, all of which matter for a search 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 action and resource, with no redundant filler. The trailing REST-endpoint sentence is low-value for tool selection but harmless and compact.

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 readOnlyHint covering safety and a fully documented six-parameter schema, most of what an agent needs is present. The gap is that there is no output schema and the description does not describe the return shape or pagination semantics, and it does not position the tool against the similarly named list_persons sibling.

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 six parameters (term, limit, cursor, fields, exact_match, organization_id) are already documented in the schema. The phrase 'across selected fields' loosely maps to the fields parameter but adds no syntax, defaults, or format detail beyond what the schema provides — baseline 3 is appropriate.

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

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

The description states a specific verb and resource ('Search persons (contacts) by term across selected fields'), and adds the useful synonym 'contacts' plus the search scope (selected fields). It never distinguishes this from the closely-named sibling pipedrive_list_persons or from pipedrive_search_items, so an agent must infer the difference from the name alone.

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

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

Usage is implied by 'by term' — an agent can infer this is for term-based lookup rather than enumeration — but there is no explicit when-to-use, when-not-to-use, or named alternative (e.g. list_persons for browsing, search_items for a cross-entity search). The guidance is inferable, not stated.

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