The Remarq MCP server has 5 well-defined tools with clear names and purposes. All tools have non-empty descriptions and most parameters include type information. However, there are significant gaps: parameter descriptions are minimal or absent for several inputs, output schemas are not documented, error handling guidance is limited, and no tool annotations (readOnlyHint/destructiveHint) are present. The naming follows verb_noun convention (check_connection, list_comments, create_comment, reply_to_comment, resolve_comment) which is clear and action-oriented. Input schemas use Zod validation on the backend (mcp-server/package.json shows zod dependency), but the documented schemas lack detail, for example, 'include_document' boolean has a description but 'uri' and 'status' parameters lack constraints or examples of valid values. Error responses are not visible in the provided code sample, making it impossible to verify recovery guidance. Output structure (what fields are returned) is not documented for any tool.

• Add explicit output schema documentation for all 5 tools. For list_comments, specify the structure of returned comments: fields like comment_id, uri, quote, body, author, status, created_at, replies (array). For create_comment, document what fields are returned (comment_id, created_at?). This prevents agent confusion and enables chaining to reply_to_comment.
• Expand parameter descriptions to include format and constraints. Replace 'Document URI to comment on' with 'The unique identifier or URL of the document being commented on (e.g., https://example.com/docs/123 or docs/123)'. For quote, add 'The exact text passage from the document being highlighted; must match the source exactly for anchoring to work'.
• Add pagination parameters to list_comments: limit (default 20, max 100) and offset or cursor. Document total_count in output so agents know if results are truncated and can iterate.
• Annotate write operations with tool annotations. Add destructiveHint: true to resolve_comment (closing cannot be undone). Mark create_comment and reply_to_comment as idempotent: false if they don't detect and prevent duplicate submissions, or idempotent: true if they deduplicate by (uri, quote, body, author).
• Document error scenarios and recovery paths. E.g., 'If the document URI is not found, the error will be {code: "document_not_found", message: "Document not found. Check the URI and try again with list_documents() if available."}'.
• Constrain the 'author' parameter: max 100 characters, alphanumeric + spaces. Constrain 'body': max 5000 characters. Constrain 'quote': max 1000 characters. Add these to parameter descriptions.