[Bug]: Tools Annotations not working and need specificity for mentioning annotations

[KaRtHiK-56]

🐞 Bug Summary

Tool annotations added via the admin UI or API are not persisted(For API please give us the detailed documentation on how to annotation while registering server or via tool edit from UI). They do not appear in the UI or in the tool schema JSON returned by the API. The annotations field remains empty ({}) even after successful updates.

In the above image via the Admin UI i tried adding annotation badge in the edit option as

"annotations": {
      "readOnlyHint": true,
      "destructiveHint": false,
      "idempotentHint": false,
      "openWorldHint": false
    } 
and 
"annotations": {
      "readOnlyHint": true
}

and 
{
      "readOnlyHint": true
}

but if i see in my terminal this is the response

INFO  [mcpgateway.services.tool_service] Updated tool: local-mcp-calculate-bmi
INFO:     127.0.0.1:60449 - "POST /admin/tools/4c5ad8d18d9b40a39239c487abdfc3aa/edit HTTP/1.1" 200 OK
INFO:     127.0.0.1:60449 - "GET /admin HTTP/1.1" 307 Temporary Redirect
INFO:     127.0.0.1:60449 - "GET /admin/ HTTP/1.1" 200 OK
INFO:     127.0.0.1:60449 - "GET /static/admin.js HTTP/1.1" 304 Not Modified
INFO:     127.0.0.1:60450 - "GET /static/admin.css HTTP/1.1" 304 Not Modified

But there is no reflection in UI console as mentioned in the above screenshots as well as in the /tools/ json response

{
    "id": "xxxxxxxxxxxxxxxxxxxxxxxxx",
    "originalName": "add",
    "url": "http://xxxx:8010/sse",
    "description": "Add two numbers",
    "requestType": "SSE",
    "integrationType": "MCP",
    "headers": null,
    "inputSchema": {
      "properties": {
        "a": {
          "title": "A",
          "type": "integer"
        },
        "b": {
          "title": "B",
          "type": "integer"
        }
      },
      "required": [
        "a",
        "b"
      ],
      "title": "addArguments",
      "type": "object"
    },
    **"annotations": {

    }**,
    "jsonpathFilter": "",
    "auth": null,
    "createdAt": "2025-08-18T06:54:24.968605",
    "updatedAt": "2025-08-18T06:54:24.968606",
    "enabled": true,
    "reachable": true,
    "gatewayId": "e0f6ecc3a4c74044b6809a081c1a15ab",
    "executionCount": 0,
    "metrics": {
      "totalExecutions": 0,
      "successfulExecutions": 0,
      "failedExecutions": 0,
      "failureRate": 0,
      "minResponseTime": null,
      "maxResponseTime": null,
      "avgResponseTime": null,
      "lastExecutionTime": null
    },
    "name": "local-mcp-add",
    "gatewaySlug": "local-mcp",
    "originalNameSlug": "add"
  }

---

🧩 Affected Component

Select the area of the project impacted:

• mcpgateway - API
• mcpgateway - UI (admin panel)
• mcpgateway.wrapper - stdio wrapper
• Federation or Transports
• CLI, Makefiles, or shell scripts
• Container setup (Docker/Podman/Compose)
• Other (explain below)

---

🔁 Steps to Reproduce

1. Register a gateway using the API or UI.
2. Add or edit a tool with annotations such as "readOnlyHint": true via the admin UI or API. --> also let me know how to properly use command to reflect the annotation badge via the UI as well as via curl
3. Reload the UI or fetch the tool schema via API.
4. Observe that the annotations field is empty and the UI does not display annotation hints.

---

🤔 Expected Behaviour

Annotations should be saved and shown correctly in the UI and included in the tool schema JSON returned by the API.

---

📓 Logs / Error Output

Logs show successful tool update but annotations are missing in responses and UI.

INFO  [mcpgateway.services.tool_service] Updated tool: local-mcp-calculate-bmi
INFO:     127.0.0.1:60449 - "POST /admin/tools/4c5ad8d18d9b40a39239c487abdfc3aa/edit HTTP/1.1" 200 OK
INFO:     127.0.0.1:60449 - "GET /admin HTTP/1.1" 307 Temporary Redirect
INFO:     127.0.0.1:60449 - "GET /admin/ HTTP/1.1" 200 OK
INFO:     127.0.0.1:60449 - "GET /static/admin.js HTTP/1.1" 304 Not Modified
INFO:     127.0.0.1:60450 - "GET /static/admin.css HTTP/1.1" 304 Not Modified

---

🧠 Environment Info

Key	Value
Version or commit	e.g. v0.5.0
Runtime	e.g. Python 3.11, Gunicorn

---

🧩 Additional Context (optional)

• Please let me know is there any way i can specify the annotation badges while registering the server my mentioning this tool is this badge for a server that brings list of tools.eg. 1 server that has 10 tools , if there is any way i can specifically mention this tools is read-only and this one is destructive etc...

[crivetimihai]

PR Response for Issue 774 Fix

Summary

Thanks for reporting this issue! I've identified and fixed the root cause. The problem was that the Admin UI form parsing wasn't extracting the annotations field from the form data, even though all the backend infrastructure was already in place to support annotations.

Root Cause

The issue was in the admin_add_tool and admin_edit_tool functions in mcpgateway/admin.py. The form parsing code was missing the annotations field extraction:

# Before (missing annotations)
tool_data: dict[str, Any] = {
    "name": form.get("name"),
    "url": form.get("url"),
    "description": form.get("description"),
    "headers": json.loads(form.get("headers") or "{}"),
    "input_schema": json.loads(form.get("input_schema") or "{}"),
    # annotations missing here!
    "jsonpath_filter": form.get("jsonpathFilter", ""),
    # ... rest of fields
}

Fix Applied

Files Changed: mcpgateway/admin.py

Added the missing annotations field parsing in both functions:

# After (annotations now included)
tool_data: dict[str, Any] = {
    "name": form.get("name"),
    "url": form.get("url"),
    "description": form.get("description"),
    "headers": json.loads(form.get("headers") or "{}"),
    "input_schema": json.loads(form.get("input_schema") or "{}"),
    "annotations": json.loads(form.get("annotations") or "{}"),  # ✅ Fixed
    "jsonpath_filter": form.get("jsonpathFilter", ""),
    # ... rest of fields
}

Lines changed:

• Line 1971: admin_add_tool function
• Line 2203: admin_edit_tool function

What This Fixes

✅ Admin UI Creation: Users can now set annotations when creating tools via the web interface
✅ Admin UI Editing: Users can now modify annotations when editing tools via the web interface
✅ Persistence: Annotations will now be properly saved to the database
✅ Display: Annotations will appear correctly in tool JSON responses
✅ API Compatibility: Existing API functionality remains unchanged

API Documentation (as requested)

Complete Annotations JSON Example

Here's a comprehensive example with all supported annotation types:

curl -X POST /tools \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "file-reader",
    "url": "http://example.com/api/read-file",
    "description": "Safely reads file contents",
    "annotations": {
      "readOnlyHint": true,
      "destructiveHint": false,
      "idempotentHint": true,
      "openWorldHint": false
    }
  }'

Individual Annotation Examples

Read-Only Tool:

{
  "name": "get-user-info",
  "url": "http://api.example.com/users",
  "annotations": {
    "readOnlyHint": true
  }
}

Destructive Tool:

{
  "name": "delete-file",
  "url": "http://api.example.com/files/delete",
  "annotations": {
    "destructiveHint": true,
    "idempotentHint": false
  }
}

Idempotent Tool:

{
  "name": "create-user",
  "url": "http://api.example.com/users",
  "annotations": {
    "idempotentHint": true,
    "readOnlyHint": false
  }
}

Updating tool annotations:

curl -X PUT /tools/{tool_id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "annotations": {
      "readOnlyHint": true,
      "destructiveHint": false
    }
  }'

For gateway-discovered tools:

1. Register the gateway first (tools auto-discovered):

   curl -X POST /gateways \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "name": "my-mcp-server",
       "url": "http://localhost:8080/sse"
     }'

2. Add annotations to discovered tools via PUT /tools/{tool_id}:

   curl -X PUT /tools/{discovered_tool_id} \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer $TOKEN" \
     -d '{
       "annotations": {
         "readOnlyHint": true,
         "destructiveHint": false,
         "idempotentHint": true
       }
     }'

Testing Status

✅ Syntax validation: Code compiles successfully
✅ Linting: All lint checks pass (10.00/10 maintained)
✅ Consistency: Both add and edit functions now handle annotations identically

Expected Behavior

After this fix, users should be able to:

1. Set annotations in Admin UI using JSON format like:

   {
     "readOnlyHint": true,
     "destructiveHint": false
   }

2. See annotations persist in database and API responses

3. Use all supported annotation types as documented in the MCP specification

The backend infrastructure was already complete - this was purely a UI form parsing issue. The fix is minimal, safe, and maintains full backward compatibility.

📚 Enhanced Documentation

I've also added comprehensive documentation for tool annotations:

New Documentation: docs/docs/using/tool-annotations.md

This includes:

• ✅ Complete annotation reference with all supported types
• ✅ Real-world examples for different tool scenarios
• ✅ Best practices for annotation usage
• ✅ Integration guidance for clients and UIs
• ✅ Step-by-step workflows for gateway-discovered tools

The documentation is also now linked from the main using guide for easy discovery.