MCP server for eSignatures (https://esignatures.com) - provides tools for managing contracts, templates, and template collaborators via the eSignatures API
Missing output schema documentation for all tools. Tools return TextContent with JSON response bodies, but agents cannot plan downstream calls or extract structured data without knowing response field types and names. This violates the response-shaper pattern and forces LLMs to guess output structure.
Parameter descriptions are sparse or missing for complex nested objects. For example, create_contract has 'signers' (array of objects), 'placeholder_fields' (array of objects), 'document_elements' (array), and 'emails' (nested object with 5+ fields), but many nested properties lack descriptions explaining what each field does or accepts. This forces LLMs to guess valid structures.
create_contractcreate_template
Recommendations
Document output schema for every tool. Define the response structure with field types and descriptions. For example, create_contract should document: {contract_id: string, status: string, url?: string}. Agents need to know what fields to extract and pass downstream.
Add min/max constraints and format examples to numeric and string parameters. For expires_in_hours, add: 'integer, range 1 - 8760 (1 year)'. For signing_order, add: 'integer, 1 - unlimited; signers with same order are notified simultaneously'.
Expand parameter descriptions for nested objects. For signers array, describe each sub-field: 'name (required): signer full name', 'email (optional): for delivery; required if no mobile', 'signing_order (optional): integer 1+, default sequential'.
Add error classification and recovery guidance to destructive tools. For delete_contract, append: 'Error if contract is sent (non-draft/non-test). Use withdraw_contract to cancel a sent contract instead. Draft contracts cannot be recovered once deleted.'
Implement pagination parameters (limit, offset) for list tools and document limits. Change list_recent_contracts to accept optional limit (1 - 100, default 20) and offset parameters. Return total_count and next_offset in response.
Move contract_source and mcp_query injection into server code. Agents should not see these fields as parameters. Inject automatically in the tool handler before calling the API.
Wrap raw API responses. Strip HTTP status codes, audit fields, and internal metadata. Return only user-relevant fields. For list_recent_contracts, return [{contract_id, title, status, created_at}] instead of dumping raw JSON.
No error handling guidance in tool descriptions. Tools like delete_contract and delete_template have destructive semantics but no mention of recovery options, confirmation workflows, or error classification. Agents cannot know whether errors are retryable, user-fixable, or fatal.
List tools (list_recent_contracts, list_templates, list_template_collaborators) lack pagination parameters (limit, offset, page_size) and do not document result count limits. list_recent_contracts returns 'the latest 100 contracts' but has no parameters to control or override this. Large result sets risk context window exhaustion and degrade LLM reasoning.
Tool descriptions lack context about when to use each tool vs alternatives. For example, update_template description is vague ('Updates the title, labels or the content'), it does not clarify when you would use this vs creating a new template, or whether updates affect existing contracts based on this template. Ambiguous tool selection increases hallucination.
No validation guidance for constrained parameters. create_contract accepts 'locale' as an enum with 24 options, and 'test' as yes/no, these are well-constrained. However, other parameters like 'expires_in_hours', 'signing_order', and nested fields lack min/max, format constraints, or valid value documentation in parameter descriptions. LLMs cannot infer whether '999999' is a valid hours value.
Response always returns raw JSON without post-processing. Code shows: `return [types.TextContent(type="text", text=f"Response code: {response.status_code}, response: {response.json()}")]` for all tools. This includes HTTP status codes and potentially verbose API responses (metadata, audit fields) irrelevant to chat interactions. Should strip, aggregate, and structure responses for agent consumption.
create_contract requires 'contract_source' and 'mcp_query' fields to be hardcoded ('mcpserver' and original user query). This is non-obvious to LLMs and violates the secret-injection pattern, internal system fields should be injected by the tool, not exposed as parameters. LLMs will struggle to infer these values.
No dry-run or confirmation pattern for destructive operations. delete_contract and delete_template are irreversible but have no preview, confirmation request, or warning in the tool description. Agents can accidentally delete resources without safeguards.
Tool-to-tool chaining unclear. For example, create_contract response must contain contract_id for downstream query_contract calls, but the response schema is undocumented. Similarly, list_templates response structure is unknown, agents cannot extract template_id for update_template or query_template without seeing the API response format.
Add confirmation or dry-run patterns for delete_contract and delete_template. Either require explicit 'confirm' parameter, or describe the consequences in the tool description and let clients prompt the user first.
Clarify when to use update_template vs creating a new template. Add: 'Use to modify an existing template. Updates apply only to new contracts created after the update; existing contracts based on the old template are not changed.'
Document which parameters are mutually exclusive. For create_contract, clarify: 'Either template_id OR document_elements must be provided, not both. If both are set, document_elements overrides the template content.'
Add input validation examples to descriptions. For locale, show: 'One of: en, es, fr, de, it, ... (24 languages supported)'. For test, show: 'yes for demo contracts (no fees, DEMO stamp, no reminders); no for production.'
Include chaining IDs in all responses. Ensure create_contract returns contract_id, create_template returns template_id, and list tools return all IDs needed for downstream operations (template_id, contract_id, collaborator_id).