rossum-mcp 0.3.5__py3-none-any.whl → 1.0.0__py3-none-any.whl

rossum_mcp/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.3.5"
+__version__ = "1.0.0"

rossum_mcp/server.py

@@ -17,6 +17,7 @@ from rossum_api.dtos import Token
 from rossum_mcp.logging_config import setup_logging
 from rossum_mcp.tools import (
     register_annotation_tools,
+    register_discovery_tools,
     register_document_relation_tools,
     register_email_template_tools,
     register_engine_tools,
@@ -45,6 +46,7 @@ logger.info(f"Rossum MCP Server starting in {MODE} mode")
 mcp = FastMCP("rossum-mcp-server")
 client = AsyncRossumAPIClient(base_url=BASE_URL, credentials=Token(token=API_TOKEN))
 
+register_discovery_tools(mcp)
 register_annotation_tools(mcp, client)
 register_queue_tools(mcp, client)
 register_schema_tools(mcp, client)

rossum_mcp/tools/__init__.py

@@ -3,6 +3,13 @@
 from __future__ import annotations
 
 from rossum_mcp.tools.annotations import register_annotation_tools
+from rossum_mcp.tools.catalog import (
+    TOOL_CATALOG,
+    ToolCategory,
+    ToolInfo,
+    get_catalog_summary,
+)
+from rossum_mcp.tools.discovery import register_discovery_tools
 from rossum_mcp.tools.document_relations import register_document_relation_tools
 from rossum_mcp.tools.email_templates import register_email_template_tools
 from rossum_mcp.tools.engines import register_engine_tools
@@ -15,7 +22,12 @@ from rossum_mcp.tools.users import register_user_tools
 from rossum_mcp.tools.workspaces import register_workspace_tools
 
 __all__ = [
+    "TOOL_CATALOG",
+    "ToolCategory",
+    "ToolInfo",
+    "get_catalog_summary",
     "register_annotation_tools",
+    "register_discovery_tools",
     "register_document_relation_tools",
     "register_email_template_tools",
     "register_engine_tools",

rossum_mcp/tools/annotations.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Literal
 
 from rossum_api.models.annotation import Annotation
 
-from rossum_mcp.tools.base import is_read_write_mode
+from rossum_mcp.tools.base import delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -130,6 +130,12 @@ async def _confirm_annotation(client: AsyncRossumAPIClient, annotation_id: int)
     }
 
 
+async def _delete_annotation(client: AsyncRossumAPIClient, annotation_id: int) -> dict:
+    return await delete_resource(
+        "annotation", annotation_id, client.delete_annotation, f"Annotation {annotation_id} moved to 'deleted' status"
+    )
+
+
 def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register annotation-related tools with the FastMCP server."""
 
@@ -165,3 +171,7 @@ def register_annotation_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> Non
     )
     async def confirm_annotation(annotation_id: int) -> dict:
         return await _confirm_annotation(client, annotation_id)
+
+    @mcp.tool(description="Delete an annotation. Moves to 'deleted' status (soft delete).")
+    async def delete_annotation(annotation_id: int) -> dict:
+        return await _delete_annotation(client, annotation_id)

rossum_mcp/tools/base.py

@@ -2,12 +2,16 @@
 
 from __future__ import annotations
 
+import logging
 import os
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
     from typing import Any
 
+logger = logging.getLogger(__name__)
+
 BASE_URL = os.environ.get("ROSSUM_API_BASE_URL", "").rstrip("/")
 MODE = os.environ.get("ROSSUM_MCP_MODE", "read-write").lower()
 
@@ -38,3 +42,32 @@ def truncate_dict_fields(data: dict[str, Any], fields: tuple[str, ...]) -> dict[
         if field in result:
             result[field] = TRUNCATED_MARKER
     return result
+
+
+async def delete_resource(
+    resource_type: str,
+    resource_id: int,
+    delete_fn: Callable[[int], Awaitable[None]],
+    success_message: str | None = None,
+) -> dict:
+    """Generic delete operation with read-only mode check.
+
+    Args:
+        resource_type: Name of the resource (e.g., "queue", "workspace")
+        resource_id: ID of the resource to delete
+        delete_fn: Async function that performs the deletion
+        success_message: Custom success message. If None, uses default format.
+
+    Returns:
+        Dict with "message" on success or "error" in read-only mode.
+    """
+    tool_name = f"delete_{resource_type}"
+    if not is_read_write_mode():
+        return {"error": f"{tool_name} is not available in read-only mode"}
+
+    logger.debug(f"Deleting {resource_type}: {resource_type}_id={resource_id}")
+    await delete_fn(resource_id)
+
+    if success_message is None:
+        success_message = f"{resource_type.title()} {resource_id} deleted successfully"
+    return {"message": success_message}

rossum_mcp/tools/catalog.py

@@ -0,0 +1,176 @@
+"""Tool catalog for dynamic tool discovery.
+
+Provides lightweight metadata for all MCP tools organized by category.
+This is the single source of truth for tool categorization - the agent
+fetches this catalog from MCP to avoid data duplication.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolInfo:
+    """Lightweight tool metadata for catalog."""
+
+    name: str
+    description: str
+    destructive: bool = False
+
+
+@dataclass
+class ToolCategory:
+    """A category of related tools."""
+
+    name: str
+    description: str
+    tools: list[ToolInfo]
+    keywords: list[str]
+
+
+# Tool catalog organized by functional category
+# Keywords enable automatic pre-loading based on user request text
+TOOL_CATALOG: dict[str, ToolCategory] = {
+    "annotations": ToolCategory(
+        name="annotations",
+        description="Document processing: upload, retrieve, update, and confirm annotations",
+        tools=[
+            ToolInfo("upload_document", "Upload document to queue"),
+            ToolInfo("get_annotation", "Retrieve annotation with extracted data"),
+            ToolInfo("list_annotations", "List annotations for a queue"),
+            ToolInfo("start_annotation", "Start annotation (to_review -> reviewing)"),
+            ToolInfo("bulk_update_annotation_fields", "Bulk update annotation fields"),
+            ToolInfo("confirm_annotation", "Confirm annotation (-> confirmed)"),
+            ToolInfo("delete_annotation", "Delete annotation (soft delete)", destructive=True),
+        ],
+        keywords=["annotation", "document", "upload", "extract", "confirm", "review"],
+    ),
+    "queues": ToolCategory(
+        name="queues",
+        description="Queue management: create, configure, and list document processing queues",
+        tools=[
+            ToolInfo("get_queue", "Retrieve queue details"),
+            ToolInfo("list_queues", "List all queues"),
+            ToolInfo("get_queue_schema", "Get queue's schema"),
+            ToolInfo("get_queue_engine", "Get queue's AI engine"),
+            ToolInfo("create_queue", "Create a queue"),
+            ToolInfo("update_queue", "Update queue settings"),
+            ToolInfo("get_queue_template_names", "List available queue templates"),
+            ToolInfo("create_queue_from_template", "Create queue from template"),
+            ToolInfo("delete_queue", "Delete queue (24h delayed)", destructive=True),
+        ],
+        keywords=["queue", "inbox", "connector"],
+    ),
+    "schemas": ToolCategory(
+        name="schemas",
+        description="Schema management: define and modify document field structures",
+        tools=[
+            ToolInfo("get_schema", "Retrieve schema details"),
+            ToolInfo("list_schemas", "List all schemas"),
+            ToolInfo("update_schema", "Update schema"),
+            ToolInfo("create_schema", "Create new schema"),
+            ToolInfo("patch_schema", "Add/update/remove schema fields"),
+            ToolInfo("get_schema_tree_structure", "Get lightweight schema tree"),
+            ToolInfo("prune_schema_fields", "Bulk remove schema fields"),
+            ToolInfo("delete_schema", "Delete schema", destructive=True),
+        ],
+        keywords=["schema", "field", "datapoint", "section", "multivalue", "tuple"],
+    ),
+    "engines": ToolCategory(
+        name="engines",
+        description="AI engine management: create and configure extraction/splitting engines",
+        tools=[
+            ToolInfo("get_engine", "Retrieve engine details"),
+            ToolInfo("list_engines", "List all engines"),
+            ToolInfo("update_engine", "Update engine settings"),
+            ToolInfo("create_engine", "Create new engine"),
+            ToolInfo("create_engine_field", "Create engine field mapping"),
+            ToolInfo("get_engine_fields", "List engine fields"),
+        ],
+        keywords=["engine", "ai", "extractor", "splitter", "training"],
+    ),
+    "hooks": ToolCategory(
+        name="hooks",
+        description="Extensions/webhooks: create and manage automation hooks",
+        tools=[
+            ToolInfo("get_hook", "Retrieve hook details with code"),
+            ToolInfo("list_hooks", "List all hooks for a queue"),
+            ToolInfo("create_hook", "Create new hook"),
+            ToolInfo("update_hook", "Update hook configuration"),
+            ToolInfo("list_hook_logs", "View hook execution logs"),
+            ToolInfo("list_hook_templates", "List Rossum Store templates"),
+            ToolInfo("create_hook_from_template", "Create hook from template"),
+            ToolInfo("delete_hook", "Delete hook", destructive=True),
+        ],
+        keywords=["hook", "extension", "webhook", "automation", "function", "serverless"],
+    ),
+    "email_templates": ToolCategory(
+        name="email_templates",
+        description="Email templates: configure automated email responses",
+        tools=[
+            ToolInfo("get_email_template", "Retrieve email template"),
+            ToolInfo("list_email_templates", "List email templates"),
+            ToolInfo("create_email_template", "Create email template"),
+        ],
+        keywords=["email", "template", "notification", "rejection"],
+    ),
+    "document_relations": ToolCategory(
+        name="document_relations",
+        description="Document relations: manage export/einvoice document links",
+        tools=[
+            ToolInfo("get_document_relation", "Retrieve document relation"),
+            ToolInfo("list_document_relations", "List document relations"),
+        ],
+        keywords=["document relation", "export", "einvoice"],
+    ),
+    "relations": ToolCategory(
+        name="relations",
+        description="Annotation relations: manage edit/attachment/duplicate links",
+        tools=[
+            ToolInfo("get_relation", "Retrieve relation details"),
+            ToolInfo("list_relations", "List annotation relations"),
+        ],
+        keywords=["relation", "duplicate", "attachment"],
+    ),
+    "rules": ToolCategory(
+        name="rules",
+        description="Validation rules: manage schema validation rules",
+        tools=[
+            ToolInfo("get_rule", "Retrieve rule details"),
+            ToolInfo("list_rules", "List validation rules"),
+            ToolInfo("delete_rule", "Delete rule", destructive=True),
+        ],
+        keywords=["rule", "validation", "constraint"],
+    ),
+    "users": ToolCategory(
+        name="users",
+        description="User management: list users and roles",
+        tools=[
+            ToolInfo("get_user", "Retrieve user details"),
+            ToolInfo("list_users", "List users with filters"),
+            ToolInfo("list_user_roles", "List available user roles"),
+        ],
+        keywords=["user", "role", "permission", "token_owner"],
+    ),
+    "workspaces": ToolCategory(
+        name="workspaces",
+        description="Workspace management: organize queues into workspaces",
+        tools=[
+            ToolInfo("get_workspace", "Retrieve workspace details"),
+            ToolInfo("list_workspaces", "List all workspaces"),
+            ToolInfo("create_workspace", "Create new workspace"),
+            ToolInfo("delete_workspace", "Delete workspace", destructive=True),
+        ],
+        keywords=["workspace", "organization"],
+    ),
+}
+
+
+def get_catalog_summary() -> str:
+    """Get a compact text summary of all tool categories for the system prompt."""
+    lines = ["Available MCP tool categories (use `list_tool_categories` for details):"]
+    for category in TOOL_CATALOG.values():
+        tool_names = ", ".join(t.name for t in category.tools)
+        lines.append(f"- **{category.name}**: {category.description} [{tool_names}]")
+    return "\n".join(lines)

rossum_mcp/tools/discovery.py

@@ -0,0 +1,37 @@
+"""Discovery tools for dynamic tool loading.
+
+Provides MCP tool to explore available tool categories and their metadata.
+The agent uses this to fetch the catalog and load tools on-demand.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import TYPE_CHECKING
+
+from rossum_mcp.tools.catalog import TOOL_CATALOG
+
+if TYPE_CHECKING:
+    from fastmcp import FastMCP
+
+
+def register_discovery_tools(mcp: FastMCP) -> None:
+    """Register discovery tools with the FastMCP server."""
+
+    @mcp.tool(
+        description="List all available tool categories with descriptions, tool names, and keywords. "
+        "Use this to discover what tools are available, then use load_tool_category to load "
+        "tools from specific categories before using them. Tools with destructive=true require "
+        "explicit user request to use (delete operations)."
+    )
+    async def list_tool_categories() -> list[dict]:
+        return [
+            {
+                "name": category.name,
+                "description": category.description,
+                "tool_count": len(category.tools),
+                "tools": [asdict(tool) for tool in category.tools],
+                "keywords": category.keywords,
+            }
+            for category in TOOL_CATALOG.values()
+        ]

rossum_mcp/tools/email_templates.py

@@ -38,15 +38,11 @@ async def _list_email_templates(
     if name is not None:
         filters["name"] = name
 
-    if first_n is not None:
-        templates_iter = client.list_email_templates(**filters)
-        templates_list: list[EmailTemplate] = []
-        n = 0
-        while n < first_n:
-            templates_list.append(await anext(templates_iter))
-            n += 1
-    else:
-        templates_list = [template async for template in client.list_email_templates(**filters)]
+    templates_list: list[EmailTemplate] = []
+    async for template in client.list_email_templates(**filters):
+        templates_list.append(template)
+        if first_n is not None and len(templates_list) >= first_n:
+            break
 
     return templates_list
 

rossum_mcp/tools/hooks.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 from rossum_api.models.hook import Hook, HookRunData, HookType
 
-from rossum_mcp.tools.base import TRUNCATED_MARKER, is_read_write_mode
+from rossum_mcp.tools.base import TRUNCATED_MARKER, delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -56,15 +56,11 @@ async def _list_hooks(
     if active is not None:
         filters["active"] = active
 
-    if first_n is not None:
-        hooks_iter = client.list_hooks(**filters)
-        hooks_list: list[Hook] = []
-        n = 0
-        while n < first_n:
-            hooks_list.append(await anext(hooks_iter))
-            n += 1
-    else:
-        hooks_list = [hook async for hook in client.list_hooks(**filters)]
+    hooks_list: list[Hook] = []
+    async for hook in client.list_hooks(**filters):
+        hooks_list.append(hook)
+        if first_n is not None and len(hooks_list) >= first_n:
+            break
 
     return hooks_list
 
@@ -238,6 +234,10 @@ async def _create_hook_from_template(
     return {"error": "Hook wasn't likely created. Hook ID not available."}
 
 
+async def _delete_hook(client: AsyncRossumAPIClient, hook_id: int) -> dict:
+    return await delete_resource("hook", hook_id, client.delete_hook)
+
+
 def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register hook-related tools with the FastMCP server."""
 
@@ -256,7 +256,7 @@ def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
         return await _list_hooks(client, queue_id, active, first_n)
 
     @mcp.tool(
-        description="Create a new hook. If token_owner is provided, organization_group_admin users CANNOT be used (API will reject)."
+        description="Create a new hook. For function hooks: 'source' in config is auto-renamed to 'function', runtime defaults to 'python3.12', timeout_s is capped at 60s. If token_owner is provided, organization_group_admin users CANNOT be used."
     )
     async def create_hook(
         name: str,
@@ -341,3 +341,7 @@ def register_hook_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
         token_owner: str | None = None,
     ) -> Hook | dict:
         return await _create_hook_from_template(client, name, hook_template_id, queues, events, token_owner)
+
+    @mcp.tool(description="Delete a hook.")
+    async def delete_hook(hook_id: int) -> dict:
+        return await _delete_hook(client, hook_id)

rossum_mcp/tools/queues.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 import os
 from dataclasses import replace
-from typing import TYPE_CHECKING, cast
+from typing import TYPE_CHECKING, Literal, cast, get_args
 
 from rossum_api import APIClientError
 from rossum_api.domain_logic.resources import Resource
@@ -14,7 +14,7 @@ from rossum_api.models.engine import Engine
 from rossum_api.models.queue import Queue
 from rossum_api.models.schema import Schema
 
-from rossum_mcp.tools.base import build_resource_url, is_read_write_mode, truncate_dict_fields
+from rossum_mcp.tools.base import build_resource_url, delete_resource, is_read_write_mode, truncate_dict_fields
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -46,10 +46,15 @@ async def _get_queue(client: AsyncRossumAPIClient, queue_id: int) -> Queue:
 
 
 async def _list_queues(
-    client: AsyncRossumAPIClient, workspace_id: int | None = None, name: str | None = None
+    client: AsyncRossumAPIClient,
+    id: str | None = None,
+    workspace_id: int | None = None,
+    name: str | None = None,
 ) -> list[Queue]:
-    logger.debug(f"Listing queues: workspace_id={workspace_id}, name={name}")
+    logger.debug(f"Listing queues: id={id}, workspace_id={workspace_id}, name={name}")
     filters: dict[str, int | str] = {}
+    if id is not None:
+        filters["id"] = id
     if workspace_id is not None:
         filters["workspace"] = workspace_id
     if name is not None:
@@ -155,8 +160,14 @@ async def _update_queue(client: AsyncRossumAPIClient, queue_id: int, queue_data:
     return cast("Queue", client._deserializer(Resource.Queue, updated_queue_data))
 
 
+async def _delete_queue(client: AsyncRossumAPIClient, queue_id: int) -> dict:
+    return await delete_resource(
+        "queue", queue_id, client.delete_queue, f"Queue {queue_id} scheduled for deletion (starts after 24 hours)"
+    )
+
+
 # Available template names for create_queue_from_template
-QUEUE_TEMPLATE_NAMES = (
+QueueTemplateName = Literal[
     "EU Demo Template",
     "AP&R EU Demo Template",
     "Tax Invoice EU Demo Template",
@@ -177,13 +188,14 @@ QUEUE_TEMPLATE_NAMES = (
     "Credit Note Demo Template",
     "Debit Note Demo Template",
     "Proforma Invoice Demo Template",
-)
+]
+QUEUE_TEMPLATE_NAMES = get_args(QueueTemplateName)
 
 
 async def _create_queue_from_template(
     client: AsyncRossumAPIClient,
     name: str,
-    template_name: str,
+    template_name: QueueTemplateName,
     workspace_id: int,
     include_documents: bool = False,
     engine_id: int | None = None,
@@ -226,9 +238,11 @@ def register_queue_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     async def get_queue(queue_id: int) -> Queue:
         return await _get_queue(client, queue_id)
 
-    @mcp.tool(description="List all queues with optional filters.")
-    async def list_queues(workspace_id: int | None = None, name: str | None = None) -> list[Queue]:
-        return await _list_queues(client, workspace_id, name)
+    @mcp.tool(description="List all queues with optional filters. id accepts comma-separated values (e.g. '1,2,3').")
+    async def list_queues(
+        id: str | None = None, workspace_id: int | None = None, name: str | None = None
+    ) -> list[Queue]:
+        return await _list_queues(client, id, workspace_id, name)
 
     @mcp.tool(description="Retrieve queue schema.")
     async def get_queue_schema(queue_id: int) -> Schema:
@@ -271,6 +285,12 @@ def register_queue_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     async def update_queue(queue_id: int, queue_data: dict) -> Queue | dict:
         return await _update_queue(client, queue_id, queue_data)
 
+    @mcp.tool(
+        description="Delete a queue. Deletion starts after 24 hours. Also deletes all related objects (annotations, documents)."
+    )
+    async def delete_queue(queue_id: int) -> dict:
+        return await _delete_queue(client, queue_id)
+
     @mcp.tool(description="Get available queue template names for create_queue_from_template.")
     async def get_queue_template_names() -> list[str]:
         return list(QUEUE_TEMPLATE_NAMES)
@@ -281,19 +301,11 @@ def register_queue_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     )
     async def create_queue_from_template(
         name: str,
-        template_name: str,
+        template_name: QueueTemplateName,
         workspace_id: int,
         include_documents: bool = False,
         engine_id: int | None = None,
     ) -> Queue | dict:
-        """
-        Available templates: EU Demo Template, AP&R EU Demo Template, Tax Invoice EU Demo Template,
-        US Demo Template, AP&R US Demo Template, Tax Invoice US Demo Template, UK Demo Template,
-        AP&R UK Demo Template, Tax Invoice UK Demo Template, CZ Demo Template, Empty Organization Template,
-        Delivery Notes Demo Template, Delivery Note Demo Template, Chinese Invoices (Fapiao) Demo Template,
-        Tax Invoice CN Demo Template, Certificates of Analysis Demo Template, Purchase Order Demo Template,
-        Credit Note Demo Template, Debit Note Demo Template, Proforma Invoice Demo Template.
-        """
         return await _create_queue_from_template(
             client, name, template_name, workspace_id, include_documents, engine_id
         )

rossum_mcp/tools/rules.py

@@ -7,6 +7,8 @@ from typing import TYPE_CHECKING
 
 from rossum_api.models.rule import Rule
 
+from rossum_mcp.tools.base import delete_resource
+
 if TYPE_CHECKING:
     from fastmcp import FastMCP
     from rossum_api import AsyncRossumAPIClient
@@ -39,6 +41,10 @@ async def _list_rules(
     return rules_list
 
 
+async def _delete_rule(client: AsyncRossumAPIClient, rule_id: int) -> dict:
+    return await delete_resource("rule", rule_id, client.delete_rule)
+
+
 def register_rule_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register rule-related tools with the FastMCP server."""
 
@@ -51,3 +57,7 @@ def register_rule_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
         schema_id: int | None = None, organization_id: int | None = None, enabled: bool | None = None
     ) -> list[Rule]:
         return await _list_rules(client, schema_id, organization_id, enabled)
+
+    @mcp.tool(description="Delete a rule.")
+    async def delete_rule(rule_id: int) -> dict:
+        return await _delete_rule(client, rule_id)

rossum_mcp/tools/schemas.py

@@ -7,10 +7,11 @@ import logging
 from dataclasses import asdict, dataclass, is_dataclass, replace
 from typing import TYPE_CHECKING, Any, Literal
 
+from rossum_api import APIClientError
 from rossum_api.domain_logic.resources import Resource
 from rossum_api.models.schema import Schema
 
-from rossum_mcp.tools.base import TRUNCATED_MARKER, is_read_write_mode
+from rossum_mcp.tools.base import TRUNCATED_MARKER, delete_resource, is_read_write_mode
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -427,9 +428,14 @@ def apply_schema_patch(
     return content
 
 
-async def _get_schema(client: AsyncRossumAPIClient, schema_id: int) -> Schema:
-    schema: Schema = await client.retrieve_schema(schema_id)
-    return schema
+async def _get_schema(client: AsyncRossumAPIClient, schema_id: int) -> Schema | dict:
+    try:
+        schema: Schema = await client.retrieve_schema(schema_id)
+        return schema
+    except APIClientError as e:
+        if e.status_code == 404:
+            return {"error": f"Schema {schema_id} not found"}
+        raise
 
 
 @dataclass
@@ -666,8 +672,10 @@ async def _patch_schema(
     return updated_schema
 
 
-async def _get_schema_tree_structure(client: AsyncRossumAPIClient, schema_id: int) -> list[dict]:
+async def _get_schema_tree_structure(client: AsyncRossumAPIClient, schema_id: int) -> list[dict] | dict:
     schema = await _get_schema(client, schema_id)
+    if isinstance(schema, dict):
+        return schema
     content_dicts: list[dict[str, Any]] = [
         asdict(section) if is_dataclass(section) else dict(section)  # type: ignore[arg-type]
         for section in schema.content
@@ -715,11 +723,15 @@ async def _prune_schema_fields(
     return {"removed_fields": sorted(removed), "remaining_fields": sorted(remaining_ids)}
 
 
+async def _delete_schema(client: AsyncRossumAPIClient, schema_id: int) -> dict:
+    return await delete_resource("schema", schema_id, client.delete_schema)
+
+
 def register_schema_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     """Register schema-related tools with the FastMCP server."""
 
     @mcp.tool(description="Retrieve schema details.")
-    async def get_schema(schema_id: int) -> Schema:
+    async def get_schema(schema_id: int) -> Schema | dict:
         return await _get_schema(client, schema_id)
 
     @mcp.tool(description="List all schemas with optional filters.")
@@ -737,6 +749,8 @@ def register_schema_tools(mcp: FastMCP, client: AsyncRossumAPIClient) -> None:
     @mcp.tool(
         description="""Patch schema nodes (add/update/remove fields in a schema).
 
+You MUST load `schema-patching` skill first to avoid errors.
+
 Operations:
 - add: Create new field. Requires parent_id (section or tuple id) and node_data.
 - update: Modify existing field. Requires node_data with fields to change.
@@ -748,7 +762,8 @@ Node types for add:
 - Multivalue (table): {"label": "Table", "category": "multivalue", "children": <tuple>}
 - Tuple (table row): {"id": "row_id", "label": "Row", "category": "tuple", "children": [<datapoints with id>]}
 
-Important: Datapoints inside a tuple MUST have an "id" field. Section-level datapoints get id from node_id parameter."""
+Important: Datapoints inside a tuple MUST have an "id" field. Section-level datapoints get id from node_id parameter.
+"""
     )
     async def patch_schema(
         schema_id: int,
@@ -761,7 +776,7 @@ Important: Datapoints inside a tuple MUST have an "id" field. Section-level data
         return await _patch_schema(client, schema_id, operation, node_id, node_data, parent_id, position)
 
     @mcp.tool(description="Get lightweight tree structure of schema with only ids, labels, categories, and types.")
-    async def get_schema_tree_structure(schema_id: int) -> list[dict]:
+    async def get_schema_tree_structure(schema_id: int) -> list[dict] | dict:
         return await _get_schema_tree_structure(client, schema_id)
 
     @mcp.tool(
@@ -779,3 +794,7 @@ Returns dict with removed_fields and remaining_fields lists. Sections cannot be
         fields_to_remove: list[str] | None = None,
     ) -> dict:
         return await _prune_schema_fields(client, schema_id, fields_to_keep, fields_to_remove)
+
+    @mcp.tool(description="Delete a schema. Fails if schema is linked to a queue or annotation (HTTP 409).")
+    async def delete_schema(schema_id: int) -> dict:
+        return await _delete_schema(client, schema_id)