Tool Composition

Guide AI on how to chain tools together across MCPs

Intelligent Chaining

Composition hints tell the AI when and how to use external MCP tools alongside Suparank tools. The AI receives these hints with tool responses and decides intelligently when to chain tools.

Configuration

Add tool instructions to your credentials file:

~/.suparank/credentials.jsonjson

{
  "tool_instructions": [
    {
      "tool_name": "keyword_research",
      "composition_hints": "For accurate search volume, use seo-research-mcp's get_keyword_data tool first. Pass the real data to enhance keyword suggestions."
    },
    {
      "tool_name": "content_write",
      "composition_hints": "Before writing, consider using firecrawl-mcp to scrape top-ranking competitor pages. Use their structure and topics to inform the content outline."
    }
  ]
}

Configuration Fields

Parameter	Type	Required	Default	Description
tool_name	`string`	Required	—	The Suparank tool this hint applies to
composition_hints	`string`	Required	—	Instructions for the AI on how to enhance this tool with external MCPs

How Hints Are Used

Tool Execution

When a Suparank tool runs, it checks for matching composition hints.

Response Enhancement

Relevant hints are appended to the tool's response.

AI Guidance

The AI sees the hints along with available external MCPs.

Intelligent Chaining

AI decides when to use external tools based on hints and context.

Example Hints

SEO Research Enhancement

{
  "tool_name": "keyword_research",
  "composition_hints": "For accurate search volume data, use seo-research-mcp's get_keyword_data tool first. This provides real search volumes from Ahrefs/Semrush. Pass this data to enhance keyword strategy recommendations."
}

Content Research

{
  "tool_name": "content_write",
  "composition_hints": "Before writing, consider using firecrawl-mcp to scrape the top 3 ranking pages for the target keyword. Analyze their: 1) Content structure (H2/H3 headings), 2) Word count, 3) Topics covered. Use these insights to create more comprehensive content."
}

Backlink Analysis

{
  "tool_name": "internal_links",
  "composition_hints": "For comprehensive link strategy, use seo-research-mcp's get_backlinks tool to analyze competitor backlink profiles. Identify linking opportunities and anchor text patterns."
}

Full Configuration Example

A complete setup with external MCPs and composition hints:

~/.suparank/credentials.jsonjson

{
  "external_mcps": [
    {
      "name": "seo-research-mcp",
      "description": "Real keyword data from SEO APIs",
      "available_tools": ["get_keyword_data", "analyze_serp", "get_backlinks"]
    },
    {
      "name": "firecrawl-mcp",
      "description": "Web scraping for competitor analysis",
      "available_tools": ["scrape_url", "crawl_site"]
    }
  ],
  "tool_instructions": [
    {
      "tool_name": "keyword_research",
      "composition_hints": "Use seo-research-mcp for real search volumes."
    },
    {
      "tool_name": "content_write",
      "composition_hints": "Use firecrawl-mcp to analyze competitor content first."
    },
    {
      "tool_name": "seo_strategy",
      "composition_hints": "Combine seo-research-mcp SERP analysis with strategy planning."
    }
  ]
}

AI Response with Hints

When the AI calls a Suparank tool, the response includes composition guidance:

[Tool Response: keyword_research results...]

---
COMPOSITION HINTS:
For accurate search volume data, use seo-research-mcp's get_keyword_data tool.
Available external MCPs: seo-research-mcp, firecrawl-mcp
---

The AI uses this information to decide whether to call external tools for enhanced results.

Best Practices

Be Specific

Tell the AI exactly which external tool to use and when

Explain Why

Help the AI understand the benefit of chaining tools

Suggest Flow

Describe the order of operations for best results

Keep Focused

One clear instruction per hint for better AI comprehension