This server has 25 tools with significant quality gaps across naming, descriptions, and schemas. Most tool names follow the verb_noun pattern correctly (e.g., pipedrive_list_deals, pipedrive_create_deal), but parameter descriptions are severely lacking. The baseline from production tools expects 100% of parameters to have descriptions, this server has many parameters with null or missing descriptions (e.g., 'value', 'currency', 'person_id' in pipedrive_create_deal lack descriptions). Enum constraints are present for some parameters (status, type) but not all. Output schemas are not documented anywhere in the provided code. Critical pattern violations: (1) Missing or null parameter descriptions on ~60% of parameters across all tools, making it impossible for LLMs to infer what values to pass; (2) No documented output schemas, LLMs cannot plan downstream calls or know what fields will be returned; (3) No error handling or recovery guidance visible in the source code. The tool descriptions themselves are brief but present (10-50 chars each), which is on the lower end of the baseline (p10=34 chars) and lacks the WHEN/WHY context production tools provide. This server would require significant refactoring to meet production standards.
Pervasive missing or null parameter descriptions: ~60% of parameters lack meaningful descriptions (e.g., 'value', 'currency', 'person_id', 'sort', 'filter_id' across all tools show null descriptions). This prevents LLMs from understanding what values to pass.
Add non-null descriptions to 100% of parameters. For each parameter, explain: What does it control? What values are valid? What is the default? Example: 'value': {'type': 'number', 'description': 'Deal value in the specified currency. Must be non-negative. Leave empty to omit value from deal.'}
Document the output schema for every tool. Include field names, types, and which fields are safe to chain into downstream tools. Example for pipedrive_get_deal: 'Returns: {deal_id: number, title: string, value: number, currency: string, person_id: number, stage_id: number, status: enum[open|won|lost], ...}'
Expand tool descriptions from 30-50 chars to 80-150 chars. Include: What does the tool do? When should the LLM call it instead of similar tools? What structure does it return? Example: 'List all open or closed deals with optional filtering by status, pipeline, or stage. Returns paginated results. Use search_deals for text-based search by deal title.'
Add explicit error handling guidance in tool descriptions or via structured error responses. Example: 'If a deal_id is not found, the tool returns 404. Suggest to the user: "Deal not found. Try search_deals() with the deal title or person name."'
Annotate write operations (create_*, update_*) with explicit state-change language: 'Modifies CRM state. This call is idempotent if the same deal_id and fields are provided, but creates a new deal entry if deal_id is omitted.'
Add type suffixes to ID and identifier parameters. E.g., rename 'person_id' → 'person_id' (already correct), but ensure 'filter_id' is renamed to 'deal_filter_id' and described as 'Pipedrive filter ID. Use list_pipelines or list_stages to discover available filters.'
No error handling or recovery guidance visible: The provided source code contains no tool-level error handling, validation, or user-facing error recovery paths. Try search_persons() instead.').
Tool descriptions are too brief and lack WHEN/WHY context: Most descriptions are 30-50 characters (below baseline p10=34 chars) and lack guidance on when to use the tool vs similar alternatives. E.g., 'List deals with optional filtering and pagination' does not answer: Why use this instead of search_deals? What fields are returned?
Inconsistent parameter naming conventions: Some parameters use bare names ('value', 'currency', 'sort', 'filter_id') without type suffixes. Compare 'filter_id' (what filter?) vs 'deal_filter_id' or 'filter_id' with a description explaining what filters are available.
Pagination info incomplete: List tools accept 'start' and 'limit' but no documented total_count or next_cursor returned. The description states 'max:500' for limit but no guidance on recommended defaults or when pagination becomes necessary.
Improve enum constraints: For 'status' in list operations, add a description like 'Filter by deal status. One of: open, won, lost, all_not_deleted. Defaults to all_not_deleted.' Similarly for 'type' in activities.
For complex objects like 'value' in pipedrive_create_lead (with 'amount' and 'currency' properties), add inline schema documentation: {'type': 'object', 'description': 'Expected deal value. Example: {"amount": 50000, "currency": "USD"}.', 'properties': {'amount': {...}, 'currency': {...}}}
Implement input validation and return specific error messages. If an agent passes an invalid status, return: 'Invalid status: "pending". Must be one of: open, won, lost, all_not_deleted.' rather than a generic 400 error.
Document pagination limits and defaults in tool descriptions. State: 'Returns up to 100 results per page (maximum 500). Use start and limit to paginate. Total result count is returned in the response.'
Add context about field resolution: The PipedriveClient has a resolveCustomFields method that suggests custom fields are available. Document which tools return custom fields and how LLMs should handle them.