ISSUE #240 | MCP tool annotation support in hayhooks

[Hrushi11]

[Issue #240] | Add MCP Tool Annotations support for pipeline tools

Problem

When Hayhooks exposes pipelines as MCP tools, the Tool objects are created with only name, description, and inputSchema no annotations. MCP clients like Claude Desktop rely on these annotations to understand tool behavior. Without them, clients default to the most pessimistic settings:

• Destructive: true (client thinks it might delete data)
• Read-only: false (client thinks it modifies state)
• Idempotent: false (client thinks repeated calls have side effects)
• No human-readable title (falls back to the raw pipeline name)

This leads to unnecessary confirmation prompts and sub-optimal tool selection in MCP clients.

Changes

• mcp_utils.py: list_pipelines_as_tools now builds a ToolAnnotations object from pipeline metadata and attaches it to each Tool. Sensible defaults are applied for typical query/RAG pipelines (readOnly=True, destructive=False, idempotent=True, openWorld=True, auto-generated title).

• base_pipeline_wrapper.py: Added MCPToolHints TypedDict and a tool_hints class attribute on BasePipelineWrapper, so wrapper-based pipelines can declare hints directly in Python.

• deploy_utils.py: Propagates tool_hints through the deploy path into registry metadata — both for wrapper-based pipelines (read from the wrapper attribute) and YAML pipelines (read from metadata.tool_hints in the YAML file, or overridable via deploy options).

Usage

Python wrapper:

class PipelineWrapper(BasePipelineWrapper):
    tool_hints = {
        "title": "Website Q&A",
        "readOnly": True,
        "destructive": False,
        "idempotent": True,
        "openWorld": False,
    }

YAML pipeline:

metadata:
  tool_hints:
    title: Calculator
    readOnly: true
    destructive: false

All fields are optional — if tool_hints is omitted entirely, defaults are applied.

Tests

• test_pipeline_tool_hints_override_default_annotations — custom hints from wrapper
• test_deploy_pipeline_files_stores_tool_hints — hints persisted in registry metadata
• test_deploy_yaml_pipeline_reads_tool_hints_from_metadata — hints from YAML metadata block
• Added annotation assertions to existing test_list_pipelines_as_tools and integration test