reader_delete_document

Instructions

Delete one or more documents from your Readwise Reader library.

Args:
    ids: (Required) Array of document IDs to delete (at least one)

Returns:
    DeleteDocumentResponse with deleted count and ids

Implementation Reference

• main.py:612-670 (handler)

  The async function reader_delete_document that implements the tool's core logic: validates IDs, calls the Reader API's /delete/{doc_id}/ endpoint for each ID, collects deleted IDs, and returns a DeleteDocumentResponse.

  @mcp.tool(
      name="reader_delete_document",
      annotations=ToolAnnotations(
          readOnlyHint=False,
          destructiveHint=True,
          idempotentHint=False,
          openWorldHint=True,
      ),
  )
  async def reader_delete_document(
      ids: List[str],
  ) -> DeleteDocumentResponse:
      """
      Delete one or more documents from your Readwise Reader library.
  
      Args:
          ids: (Required) Array of document IDs to delete (at least one)
  
      Returns:
          DeleteDocumentResponse with deleted count and ids
      """
      ctx = get_reader_context()
      logger.info(f"reader_delete_document: {len(ids)} documents")
  
      try:
          # Validate IDs
          if not ids:
              raise ValueError("IDs array is required and cannot be empty.")
          if not isinstance(ids, list):
              raise ValueError("IDs must be an array of document IDs.")
  
          deleted_ids = []
          for doc_id in ids:
              try:
                  response = await ctx.client.delete(f"/delete/{doc_id}/")
                  response.raise_for_status()
                  deleted_ids.append(doc_id)
              except httpx.HTTPStatusError as e:
                  if e.response.status_code == 404:
                      logger.warning(f"Document not found: {doc_id}, skipping...")
                  else:
                      logger.error(f"Error deleting {doc_id}: {e}")
  
          return DeleteDocumentResponse(
              deleted=len(deleted_ids),
              ids=deleted_ids,
          )
  
      except httpx.HTTPStatusError as e:
          if e.response.status_code == 401:
              raise ValueError("Authentication failed. Please check your access token.")
          elif e.response.status_code == 429:
              raise _rate_limit_error(e.response)
          raise
      except ValueError as e:
          raise
      except Exception as e:
          logger.error(f"Error in reader_delete_document: {str(e)}")
          raise ValueError(f"Failed to delete documents: {str(e)}")

• models.py:114-118 (schema)

  The DeleteDocumentResponse dataclass schema with 'deleted' (int) and 'ids' (List[str]) fields.

  @dataclass
  class DeleteDocumentResponse:
      """Response from deleting document(s)"""
      deleted: int
      ids: List[str]

• main.py:612-619 (registration)

  The @mcp.tool registration decorator with name='reader_delete_document', annotations including destructiveHint=True.

  @mcp.tool(
      name="reader_delete_document",
      annotations=ToolAnnotations(
          readOnlyHint=False,
          destructiveHint=True,
          idempotentHint=False,
          openWorldHint=True,
      ),