Read deals, persons, organizations, activities and pipelines; create and update CRM records.
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 3.9/5 across 19 of 19 tools scored. Lowest: 3.1/5.
Each tool targets a distinct resource and action, with clear separation between create, get, list, and search operations. The global search tool is explicitly differentiated from entity-specific searches, and pipelines/stages/current_user are unique. No two tools appear to serve the same purpose.
Tool names follow a consistent verb_noun pattern (e.g., list_deals, get_person, create_activity), with the exception of 'add_note' using 'add' instead of 'create'. This is a minor deviation that does not cause confusion, but the inconsistency between add and create is noticeable.
At 19 tools, the server covers a broad set of CRM entities and operations, which is reasonable for the scope. While it is on the heavier side, each tool serves a distinct function and none are redundant. The count feels justified for a comprehensive CRM integration.
The server lacks update and delete operations for all entities, and there is no create operation for organizations, pipelines, or stages. This creates significant gaps that would prevent agents from modifying existing records or creating certain entities. The read and search capabilities are solid, but the lifecycle coverage is severely incomplete.
pipedrive_add_noteAdd noteAAdd a note, linked to at least one of a deal/person/organization/lead. content is required (HTML or plain text). Uses v1 (v2 has no notes endpoint). Pipedrive REST: POST /api/v1/notes.
| Name | Required | Description | Default |
|---|---|---|---|
| org_id | No | Attach to this organization id. | |
| content | Yes | Note body — HTML or plain text (required). | |
| deal_id | No | Attach to this deal id. | |
| lead_id | No | Attach to this lead id (a UUID string). | |
| person_id | No | Attach to this person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation declares destructiveHint: true, but the description clearly indicates a non-destructive create operation ('Add a note', 'POST /api/v1/notes'). This is a direct contradiction. The description does mention the API endpoint and version, but the conflict with annotations severely undermines behavioral transparency.
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 sentences long, front-loaded with the core purpose, and every sentence adds useful information (requirements, API version/endpoint). There is no wasted wording.
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 creation tool, the description provides essential context: purpose, required field, linking requirement, and API details. Since there is no output schema, it doesn't need to explain return values. It lacks info on permissions or error cases, but that's not critical here. The main issue is the annotation contradiction, which is scored separately.
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 schema already describes all parameters (100% coverage), so the baseline is 3. The description adds the key semantic constraint that the note must be linked to at least one of deal/person/organization/lead, which is not enforced in the schema. It also clarifies that content can be HTML or plain text. This adds value 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 clearly states the tool's function: 'Add a note' with a specific resource (a note) and the ability to link it to deals, persons, organizations, or leads. This distinctly differentiates it from sibling tools like pipedrive_list_notes or pipedrive_create_activity.
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 context on when to use the tool: content is required, and the note must be linked to at least one entity. It also notes the API version choice (v1) because v2 has no notes endpoint. While it doesn't explicitly name alternatives, the guidance is sufficient for choosing this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_create_activityCreate activityACreate a new activity (task/event). subject is required; link it to a deal/person/org and set type/date/time as needed. Pipedrive REST: POST /api/v2/activities.
| Name | Required | Description | Default |
|---|---|---|---|
| done | No | Whether the activity is already marked done. | |
| note | No | Free-text note attached to the activity. | |
| type | No | Activity type key, e.g. 'call', 'meeting', 'task', 'email'. | |
| org_id | No | Link to this organization id. | |
| deal_id | No | Link to this deal id. | |
| subject | Yes | Activity subject/title (required). | |
| due_date | No | Due date, yyyy-mm-dd. | |
| due_time | No | Due time, HH:MM (24h). | |
| duration | No | Duration, HH:MM. | |
| owner_id | No | Assign to this owner (user) id. | |
| person_id | No | Link to this person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations declare destructiveHint=true, so the agent already knows this is a write operation. The description adds that it creates a task/event but does not disclose additional behaviors like required permissions, idempotency, or side effects. It does not contradict 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 sentences, front-loaded with the action and key constraint. Every word is informative, and no space is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 11 parameters and no output schema, the description provides the essential usage pattern and references the REST endpoint. It does not explain return values or errors, but the schema and annotations cover the rest adequately.
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 covers 100% of parameters, so the baseline is 3. The description adds strategic value by highlighting 'subject' as required and suggesting the optional linking to deal/person/org plus type/date/time, which helps prioritize the most important fields.
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 'Create a new activity (task/event)' with specificity, and distinguishes it from sibling read tools such as pipedrive_list_activities. The REST endpoint is also provided, reinforcing the action.
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 clear context on how to use the tool (required subject, linking to deal/person/org, setting type/date/time) and implies it is for creating rather than listing activities. However, it does not explicitly mention alternatives such as pipedrive_list_activities or pipedrive_add_note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_create_dealCreate dealACreate a new deal. title is required; link it to a person/org/pipeline/stage/owner as needed. Pipedrive REST: POST /api/v2/deals.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Deal title (required). | |
| value | No | Deal monetary value. | |
| org_id | No | Link to this organization id. | |
| status | No | Deal status — 'open' (default), 'won' or 'lost'. | |
| currency | No | Currency code for `value`, e.g. 'USD'. | |
| owner_id | No | Assign to this owner (user) id. | |
| stage_id | No | Place in this stage id. | |
| person_id | No | Link to this person id. | |
| visible_to | No | Visibility group id (Pipedrive visibility setting). | |
| pipeline_id | No | Place in this pipeline id. | |
| expected_close_date | No | Expected close date, yyyy-mm-dd. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include destructiveHint: true, which already signals that this tool modifies state, and the description accurately identifies it as a creation operation. The description adds the REST endpoint but doesn't disclose idempotency, required permissions, or post-condition behavior beyond what the annotation implies. It doesn't contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and essential requirement. It has no filler and effectively communicates the tool's purpose and key usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create tool with 11 parameters, the description is brief but sufficient given the complete schema and the destructiveHint annotation. It does not explain the return value or error cases, but no output schema exists and the operation is straightforward, so a note on return behavior would be helpful but not essential.
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 parameters are already well documented. The description adds high-level guidance that title is required and suggests connecting the deal to related entities (person/org/pipeline/stage/owner), which helps agents understand parameter relationships and usage context 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 uses the specific verb 'Create' with the resource 'deal' and includes the REST endpoint, making the tool's function unmistakable. It clearly distinguishes from siblings like list_deals, get_deal, or search_deals by focusing on the creation action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states that title is required and suggests linking to person/org/pipeline/stage/owner as needed, providing clear context on how to use the tool. It does not explicitly mention alternatives or when not to use it, but the verb 'Create' and sibling names make the use case obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_create_personCreate personACreate a new person (contact). name is required; email/phone are convenience strings mapped to Pipedrive's structured emails/phones arrays. Pipedrive REST: POST /api/v2/persons.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Person full name (required). | |
| No | Primary email address (mapped to the emails array). | ||
| phone | No | Primary phone number (mapped to the phones array). | |
| org_id | No | Link to this organization id. | |
| owner_id | No | Assign to this owner (user) id. | |
| visible_to | No | Visibility group id (Pipedrive visibility setting). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes beyond the destructiveHint annotation by explaining that email/phone are convenience strings mapped to Pipedrive's structured arrays, which helps the agent understand how input relates to the API. It also mentions the REST endpoint. No contradiction with the annotation exists, and it adds useful behavioral 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?
The description is three sentences, front-loaded with the main purpose in the first sentence, and each sentence adds essential information (required field, mapping behavior, REST endpoint). No wasted words or repetition of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 6 parameters and no output schema, the description covers the core purpose, required parameter, parameter mapping, and API endpoint. It does not specify return values or explicit prerequisites, but the schema and annotations fill in most gaps, making this sufficiently complete for a straightforward creation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by framing email/phone as 'convenience strings' mapped to structured arrays, which clarifies intent beyond the schema's property descriptions. It also emphasizes that name is required, reinforcing the schema without being redundant.
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 the specific verb 'Create' and the resource 'a new person (contact)', which is clear and distinct from sibling tools like create_deal or create_activity. It also provides the exact REST endpoint (POST /api/v2/persons) and states the required field, making the tool's function 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 clearly indicates this tool is for creating persons/contacts, which is a distinct use case from the list/search/get siblings. It does not explicitly mention alternatives or when not to use it, but the context is clear enough that an agent would understand when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_get_current_userGet current userAGet the authenticated user's profile (name, email, company, locale, timezone). Pipedrive REST: GET /api/v1/users/me.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the REST endpoint (GET /api/v1/users/me) and the specific data returned. It doesn't mention error handling or response format, but for a simple read-only operation this is sufficient. No contradiction with annotations.
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 one sentence plus the REST endpoint, front-loaded with the verb and resource. Every word earns its place, and it is 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 0-parameter, read-only tool with no output schema, the description fully covers what the tool does, what it returns, and the underlying API. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (empty object). The description correctly adds no parameter details because none exist. Baseline for 0 parameters is 4.
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's purpose: 'Get the authenticated user's profile' and lists specific fields (name, email, company, locale, timezone). This distinguishes it from all sibling tools, which deal with deals, persons, organizations, activities, and 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 implies clear usage context: use when you need the current user's profile. It doesn't explicitly exclude alternatives, but given the sibling tools cover different entities, no other tool could serve this purpose. This is clear context without formal exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_get_dealGet dealAGet a single deal by its id. Pipedrive REST: GET /api/v2/deals/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Deal id (required). |
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 but no additional behavioral context such as error handling, response format, or rate limits. It is consistent with annotations but does not enrich beyond them.
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 directly states the purpose and includes the REST endpoint. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-ID operation with a well-documented parameter and read-only annotation, the description is largely adequate. It lacks explicit mention of the response, but the absence of an output schema and the simplicity of the operation make this acceptable. A 4 reflects that it is complete for practical use, though not exhaustive.
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 fully covers the only parameter (id) with a description, so schema description coverage is 100%. The description's mention of 'by its id' adds no new meaning beyond what the schema already provides. 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?
The description clearly states the action ('Get') and the resource ('a single deal by its id'), with specificity that distinguishes it from sibling tools like pipedrive_list_deals and pipedrive_search_deals. The REST endpoint further reinforces the precise operation.
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'—the agent must have a deal ID. However, there is no explicit guidance on when to use this versus listing or searching deals, nor any exclusions or alternatives mentioned. The description relies on the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_get_organizationGet organizationAGet a single organization by its id. Pipedrive REST: GET /api/v2/organizations/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Organization id (required). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds no meaningful behavioral context beyond restating the purpose and endpoint. It does not mention error handling, auth requirements, rate limits, or any side effects, though none are expected for a read operation. Minimal value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler. The endpoint provides useful technical context without bloating the 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?
For a simple single-getter tool with one required parameter, a read-only annotation, and no output schema, the description is adequately complete. It could mention not-found behavior or return shape, but these are not critical given the tool's simplicity.
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 already describes 'id' as required. The description adds only the REST path and 'by its id', which does not materially enhance parameter understanding. 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 a specific action ('Get a single organization') and resource ('by its id'), distinguishing it from sibling tools like list_organizations and search_organizations. The REST endpoint further reinforces the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific organization ID and need that single record, but it does not explicitly contrast with list/search tools or mention when not to use it. No alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_get_personGet personAGet a single person (contact) by its id. Pipedrive REST: GET /api/v2/persons/{id}.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Person id (required). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, and the description aligns by stating 'GET'. The description adds the REST method but little else, such as error behavior or authentication needs. For a simple read-only retrieval, this is adequate but not enriched beyond the structured metadata.
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 immediately states the action, resource, and key parameter. It also includes the REST endpoint for reference without unnecessary filler. 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?
The tool is simple (one required parameter, no output schema), and the description is sufficient to understand its core function. It could mention the return payload shape, but given the simplicity of a single-person fetch, the description is nearly complete. A slightly stronger description might note that it returns the person object, but this is not a major 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?
The input schema covers 100% of the parameter documentation, fully describing 'id' as a required integer. The description only repeats 'by its id', adding no new meaning. With this high schema coverage, the baseline score of 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 tool gets a single person (contact) by id, using a specific verb and resource. This distinguishes it from sibling tools like list_persons or search_persons, which operate on collections. The inclusion of the REST endpoint further clarifies the exact operation.
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 clear context: use this when you have a specific person id and need that single record. It doesn't explicitly mention alternatives like list_persons or search_persons, but the phrasing 'by its id' implies the use case and differentiates from those tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_activitiesList activitiesAList activities (tasks/events), optionally filtered by filter/owner/deal/person/org/done/updated_since. Pipedrive REST: GET /api/v2/activities.
| Name | Required | Description | Default |
|---|---|---|---|
| done | No | Filter by completion — true for done, false for not done. | |
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| org_id | No | Filter by linked organization id. | |
| deal_id | No | Filter by linked deal id. | |
| owner_id | No | Filter by owner (user) id. | |
| filter_id | No | Filter by a saved filter id. | |
| person_id | No | Filter by linked person id. | |
| updated_since | No | Only activities updated after this RFC 3339 timestamp, e.g. '2024-01-01T00:00:00Z'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already covers the read-only safety profile. The description adds the REST endpoint but no additional behavioral context such as pagination behavior, rate limits, or result size. It does not contradict the annotation, but adds minimal value beyond it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core action. The REST endpoint sentence is somewhat redundant for an agent but does not significantly bloat the description. It earns a 4 for overall efficiency.
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 comprehensive schema and readOnlyHint, the description sufficiently conveys the tool's purpose and filter capabilities. Pagination is already documented in the cursor parameter's description. It could explicitly state that it returns a list of activities, but 'List' implies that, making this complete enough.
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 all 9 parameters individually documented. The description merely lists the filter names without adding new semantic meaning, so it provides no value beyond the schema. 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 uses the specific verb 'List' with the resource 'activities', explicitly clarifies they are tasks/events, and enumerates filter dimensions. This clearly distinguishes it from sibling tools like pipedrive_create_activity and pipedrive_list_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?
The description indicates when to use the tool by stating it lists activities with optional filters, making the context clear. However, it does not explicitly mention alternatives or exclusions (e.g., when to use a search tool instead), so it falls slightly short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_dealsList dealsAList deals, optionally filtered by filter/owner/person/org/pipeline/stage/status and sorted. Pipedrive REST: GET /api/v2/deals.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| org_id | No | Filter by linked organization id. | |
| status | No | Filter by deal status — 'open', 'won', 'lost' or 'deleted'. | |
| sort_by | No | Field to sort by — 'id', 'update_time' or 'add_time'. | |
| owner_id | No | Filter by owner (user) id. | |
| stage_id | No | Filter by stage id. | |
| filter_id | No | Filter by a saved filter id. | |
| person_id | No | Filter by linked person id. | |
| pipeline_id | No | Filter by pipeline id. | |
| sort_direction | No | Sort direction — 'asc' or 'desc'. |
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 and filter/sort capabilities, which is useful but not extensive behavioral information (e.g., pagination, default sort). This matches the calibration example where annotation coverage lowers the bar; score 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with 'List deals', and every word adds value. The REST endpoint is a useful pointer. No padding or redundant restatement of the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a straightforward list operation with many optional filters, all documented in the schema. The annotations cover read-only safety. No output schema exists, and the description does not explicitly describe the return shape, but the endpoint and name make it clear that a list of deals is returned. A small gap, so 4 rather than 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 11 parameters is already self-documented. The description mentions filter/sort categories at a high level but does not add meaning beyond the schema. Per the baseline rule, a score of 3 is correct 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 and resource: 'List deals' with optional filters and sorting. It clearly distinguishes from sibling search tools by describing a listing operation with explicit filter dimensions. The REST endpoint adds precision.
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 clear context for use: listing deals with optional filters by owner, person, org, pipeline, stage, status, and sorting. It does not explicitly exclude alternatives like search_deals, but the filter/sort language implies a list-all or filtered-list use case. No when-not-to-use guidance, so not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_notesList notesAList notes, optionally filtered by user/deal/person/org/lead. Uses v1 (v2 has no notes endpoint) with start+limit pagination. Pipedrive REST: GET /api/v1/notes.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort expression, e.g. 'add_time DESC'. | |
| limit | No | Max results to return (v1 limit). | |
| start | No | Pagination offset (v1 start; default 0). | |
| org_id | No | Filter by linked organization id. | |
| deal_id | No | Filter by linked deal id. | |
| lead_id | No | Filter by linked lead id (a UUID string). | |
| user_id | No | Filter by the note author (user) id. | |
| person_id | No | Filter by linked person id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the safety profile is known. The description adds pagination behavior (start+limit) and API version context, but does not explain default sorting, filter combination semantics, or error/response details. This is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a compact 3-sentence structure that front-loads the primary purpose, then adds version and pagination details. No unnecessary words or repetition.
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 optional filter parameters and no output schema, the description provides essential context including the API endpoint and pagination approach. It lacks explicit guidance on how filters combine or what the default response looks like, but the schema and readOnlyHint cover much of the necessary context, making it mostly complete for a 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?
The schema provides 100% coverage with descriptions for all 8 parameters, so the baseline is 3. The description's mention of 'filtered by user/deal/person/org/lead' gives a high-level grouping, but adds little beyond the schema's per-parameter descriptions.
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 'List notes' and elaborates with optional filter dimensions (user/deal/person/org/lead), making the verb and resource explicit. It also distinguishes itself from the sibling pipedrive_add_note by focusing on listing rather than creating.
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 notes optional filters, indicating when you'd use this to retrieve specific subsets of notes. It also mentions v1 has no v2 equivalent, but it does not explicitly name alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_organizationsList organizationsAList organizations, optionally filtered by filter/owner and sorted. Pipedrive REST: GET /api/v2/organizations.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| sort_by | No | Field to sort by — 'id', 'update_time' or 'add_time'. | |
| owner_id | No | Filter by owner (user) id. | |
| filter_id | No | Filter by a saved filter id. | |
| sort_direction | No | Sort direction — 'asc' or 'desc'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the description adds the REST GET endpoint and optional filter/sort behavior, which is consistent. No contradiction, but no additional behavioral context like pagination or return format beyond what the schema provides.
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 with no wasted words. The first sentence states the core behavior, and the second provides the REST endpoint reference. Well structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with full schema coverage and a readOnly annotation, the description is adequate. It lacks explicit alternative tool guidance and return format details, but these are not critical given the provided schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are fully documented. The description references 'filter/owner' and 'sorted', corresponding to filter_id, owner_id, sort_by, and sort_direction, but adds no new syntax or details 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 clearly states 'List organizations' with optional filtering and sorting, using a specific verb and resource. It distinguishes itself from sibling tools like get_organization and search_organizations by focusing on the list operation with filter/sort capabilities.
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 clear context: listing organizations with optional filters by filter/owner and sorting. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough in the presence of sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_personsList personsAList persons (contacts), optionally filtered by filter/owner/org and sorted. Pipedrive REST: GET /api/v2/persons.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| org_id | No | Filter by linked organization id. | |
| sort_by | No | Field to sort by — 'id', 'update_time' or 'add_time'. | |
| owner_id | No | Filter by owner (user) id. | |
| filter_id | No | Filter by a saved filter id. | |
| sort_direction | No | Sort direction — 'asc' or 'desc'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already discloses the safe read-only nature. The description adds the REST GET path and clarifies persons as contacts, which slightly supplements but does not go beyond the annotation. No additional behavioral traits (e.g., pagination, rate limits) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences: the first states the action and optional filters/sorting, the second provides the canonical REST endpoint. Every word earns its place and the most important information 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?
For a simple read-only list operation with 7 optional, fully documented parameters and no output schema, the description covers the essential purpose and API path. It omits explicit mention of pagination behavior, but the schema's cursor description compensates. The tool is simple enough that this is largely 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%, with each parameter (limit, cursor, org_id, sort_by, owner_id, filter_id, sort_direction) having a clear description. The tool description merely lists parameter categories (filter/owner/org) without adding details beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('persons (contacts)'), clearly distinguishing it from get/single-entity tools like pipedrive_get_person and from search tools like pipedrive_search_persons. Mentioning optional filters and sorting adds scope without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use cases via 'optionally filtered by filter/owner/org and sorted' but does not explicitly state when to prefer this over siblings like pipedrive_search_persons or pipedrive_get_person. No exclusions or alternative tool recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_pipelinesList pipelinesAList all pipelines. Pipedrive REST: GET /api/v2/pipelines.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| sort_by | No | Field to sort by — 'id', 'update_time' or 'add_time'. | |
| sort_direction | No | Sort direction — 'asc' or 'desc'. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only; the description adds the REST endpoint as context, but does not disclose pagination behavior, response format, or any additional behavioral traits beyond what annotations provide.
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 filler, perfectly 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?
The description is minimal, but the schema and read-only annotation cover most needs. However, no output schema exists and the description doesn't explain return shape or pagination behavior, leaving some gaps for a list 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 covers all 4 parameters with individual descriptions, so the description adds no additional parameter semantics. 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 'List all pipelines' with a specific verb and resource, and includes the exact REST endpoint, clearly distinguishing it from sibling list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use or alternative guidance; it relies on the obvious purpose. There is no mention of when not to use or alternatives, so it's implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_list_stagesList stagesAList stages, optionally restricted to a single pipeline. Pipedrive REST: GET /api/v2/stages.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| pipeline_id | No | Restrict to stages of this pipeline id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds the behavioral detail that results can be optionally restricted to a single pipeline. However, it does not disclose additional behaviors such as default sorting, pagination handling (beyond schema), or error conditions, though the read-only nature is well-covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence followed by the REST endpoint reference. It is front-loaded with the verb and resource, contains no filler, and every word contributes to understanding the tool's purpose and primary option.
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's simplicity (3 optional params, read-only, no output schema), the description provides adequate context for the core operation and the main optional filter. It lacks explicit mention of return format or default behavior, but the schema and title cover most necessary details for a basic list endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all three parameters. The description reinforces the pipeline_id functionality but adds no new semantic meaning beyond what the schema provides, warranting the baseline score 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 uses the specific verb 'List' with the resource 'stages' and notes an optional restriction by pipeline, making it clear what the tool does. It distinguishes from sibling tools like list_pipelines and list_deals by targeting stages specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing stages and mentions the optional pipeline filter, but it does not explicitly state when to use this tool over alternatives or provide exclusions. There is no direct comparison to sibling tools, so guidance beyond the core purpose is limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_search_dealsSearch dealsASearch deals by term across selected fields. Pipedrive REST: GET /api/v2/deals/search.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term (at least 2 characters, required). | |
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| fields | No | Comma-separated fields to search — any of 'custom_fields', 'notes', 'title'. | |
| status | No | Restrict to deals with this status — 'open', 'won' or 'lost'. | |
| person_id | No | Restrict to deals linked to this person id. | |
| exact_match | No | If true, only exact matches (case-insensitive) are returned. | |
| organization_id | No | Restrict to deals linked to this organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already communicates this is a safe read operation, lowering the bar for behavioral disclosure. The description adds the REST GET endpoint but does not mention pagination behavior, default fields, or required permissions. No contradiction with annotations.
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 that is front-loaded with the action ('Search deals') and contains no redundant phrasing. Every word earns its place, making it highly efficient for an agent to parse.
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 rich schema (8 well-documented parameters) and read-only annotation, the description is sufficiently complete for a simple search tool. The cursor parameter's description already implies pagination, so the lack of explicit return-format details is acceptable. Minor gaps exist, such as not explaining what 'selected fields' defaults to, but overall 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 coverage is 100% with all 8 parameters individually described. The description's mention of 'term across selected fields' adds no substantive meaning beyond what the schema already provides, so it earns the baseline score 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 clearly states the tool searches deals by term across selected fields, which is a specific action on a specific resource. It distinguishes itself from sibling search tools (search_organizations, search_persons) by explicitly targeting deals, and includes the REST endpoint for additional context.
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 instead of alternatives like list_deals or search_items. It does not mention exclusions, prerequisites, or contrast with other deal-related tools, leaving the agent to infer usage context from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_search_itemsSearch itemsAGlobal search across multiple item types (deals, persons, organizations, products, leads, files, etc.). Pipedrive REST: GET /api/v2/itemSearch.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term (at least 2 characters, required). | |
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| fields | No | Comma-separated fields to search within (depends on item types). | |
| item_types | No | Comma-separated item types to search — any of 'deal', 'person', 'organization', 'product', 'lead', 'file', 'mail_attachment', 'project'. | |
| exact_match | No | If true, only exact matches (case-insensitive) are returned. | |
| search_for_related_items | No | If true, also return items related to the matches (e.g. deals of a matched person). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations include readOnlyHint: true, so the agent knows this is a safe read operation. The description adds the REST endpoint and the multi-type scope, but does not disclose additional behaviors like pagination details, rate limits, or return format. With annotations covering the safety profile, this is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the key purpose 'Global search'. It provides the API endpoint as additional developer context without any fluff or redundant content.
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 quite complete for tool selection. It lacks an explanation of the return format, but since no output schema exists and the search is polymorphic, this gap is minor. The overall purpose and scope are clear.
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 7 parameters are already documented thoroughly. The description itself does not add meaning beyond the schema; for example, it mentions 'item types' but that is already detailed in the item_types parameter description. 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 'Global search across multiple item types' which is a specific verb+resource+scope, and lists example item types. It distinguishes itself from sibling tools like pipedrive_search_deals by emphasizing 'global' and 'multiple item 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?
The description provides clear context for when to use the tool: when searching across multiple item types. However, it does not explicitly mention alternatives like search_deals or search_persons for single-type searches, so it lacks explicit exclusion or alternative naming.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_search_organizationsSearch organizationsBSearch organizations by term across selected fields. Pipedrive REST: GET /api/v2/organizations/search.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term (at least 2 characters, required). | |
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| fields | No | Comma-separated fields to search — any of 'address', 'custom_fields', 'name', 'notes'. | |
| exact_match | No | If true, only exact matches (case-insensitive) are returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, so the read-only nature is known. The description adds only the REST endpoint (GET /api/v2/organizations/search) which is not behavioral context. It does not disclose pagination behavior, response characteristics, or any other operational 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 two sentences long, immediately states the purpose, and includes the REST reference without any filler. Every word earns its place, making it highly concise and well-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?
The tool has full schema coverage and a read-only annotation, making it functional for simple invocation. However, there is no output schema and the description does not mention response format, pagination, or usage context, leaving some gaps for an agent trying to interpret results or compare with alternatives.
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 5 parameters described. The description's phrase 'across selected fields' references the fields parameter but does not add new meaning beyond the schema. Baseline of 3 applies because the schema handles parameter documentation.
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 'Search organizations by term across selected fields' with a specific verb (search) and resource (organizations). It distinguishes from sibling search tools like pipedrive_search_persons by naming the resource, though it doesn't explicitly contrast with pipedrive_search_items.
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 like pipedrive_list_organizations or pipedrive_search_items. There are no exclusions, prerequisites, or context about typical use cases beyond the basic search functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
pipedrive_search_personsSearch personsASearch persons (contacts) by term across selected fields. Pipedrive REST: GET /api/v2/persons/search.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | Search term (at least 2 characters, required). | |
| limit | No | Max results to return (1–500, default 100). | |
| cursor | No | Opaque pagination cursor from a previous response's `next_cursor`. | |
| fields | No | Comma-separated fields to search — any of 'name', 'email', 'phone', 'notes', 'custom_fields'. | |
| exact_match | No | If true, only exact matches (case-insensitive) are returned. | |
| organization_id | No | Restrict to persons linked to this organization id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotation readOnlyHint=true already conveys that the operation is a safe read, lowering the burden on the description. The description adds the REST endpoint and the notion of searching 'across selected fields,' which is a minor behavioral detail. It does not disclose pagination behavior, response format, or any rate limits, but these are partially covered by the schema parameters (cursor) and annotations. This is similar to the calibration example where annotations cover safety and the description adds scoping context, resulting in a 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, totaling 16 words. The first sentence front-loads the core purpose with a specific verb and resource. The second sentence provides a valuable REST endpoint reference. Every word earns its place; there is no fluff or repetition of schema details. This is an example of optimal conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and no output schema, the description needs to provide enough context for correct usage. It states the tool searches persons by term, which implies the result is a list of matching persons. The readOnlyHint annotation reassures safety, and the schema fully documents parameters. However, it does not explicitly mention that results are paginated (via cursor) or what the default result structure looks like. Given the completeness of the schema and annotations, this is adequate but has a small gap, earning a 4 rather than a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters already have detailed descriptions in the schema. The tool description mentions 'term' and 'selected fields' which map to the 'term' and 'fields' parameters, but it adds no new semantic detail beyond what the schema already provides. Per the rubric, the baseline is 3 when schema coverage is high, and the description does not elevate 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 ('Search') and the resource ('persons (contacts)'), with the specific scope 'by term across selected fields.' It distinguishes this from sibling tools like search_deals and search_organizations by explicitly naming 'persons' as the search target. The REST endpoint reference adds concrete validation.
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 context is implied rather than explicit: the description states 'Search persons by term,' which signals this tool is for finding specific persons when you have a search term. However, it does not mention alternatives like list_persons for listing all persons or search_items for a broader search, nor does it provide any when-not-to-use guidance. The sibling tool names in the context signal provide some orientation, but the description itself lacks explicit differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!