Which integrations are available for this server?

Enables technical diagram generation from Mermaid syntax, allowing the creation of charts, flowcharts, and diagrams through the image generation tool. Supports the generation of technical visualizations and diagrams using the Vega visualization grammar.

de en es ja ko ru zh

Opengraph io MCP

by securecoders

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

OpenGraph MCP Server (og-mcp)

og‑mcp is a Model‑Context‑Protocol (MCP) server that makes every OpenGraph.io ( https://opengraph.io ) API endpoint available to AI agents (e.g. Anthropic Claude, Cursor, LangGraph) through the standard MCP interface.

Why? If you already use OpenGraph.io to unfurl links, scrape HTML, extract article text, or capture screenshots, you can now give the same capabilities to your autonomous agents without exposing raw API keys.

Global Installation

You can install this package globally via npm:

npm install -g opengraph-io-mcp

Related MCP server: @hauntapi/mcp-server

Quick Install

CLI Installer (Recommended)

The easiest way to configure OpenGraph MCP for any supported client:

# Interactive mode - guides you through setup
npx opengraph-io-mcp-install

# Direct mode - specify client and app ID
npx opengraph-io-mcp-install --client cursor --app-id YOUR_APP_ID

Supported clients: cursor, claude-desktop, windsurf, vscode, zed, jetbrains

Claude Desktop Extension

For Claude Desktop users, you can also download the .mcpb extension for one-click installation from the Releases page.

Authentication

The hosted MCP server supports two authentication methods:

Option 1 — OAuth 2.1 (recommended for hosted deployments)

OAuth lets you authorize access through your OpenGraph.io dashboard without copying API keys into config files. The MCP client handles the entire browser login flow automatically.

Supported by: MCP clients that implement the Authorization Code + PKCE flow (Cursor, Claude Desktop 0.10+, VS Code with the MCP extension).

When the client connects with no credentials, the server returns 401 with a WWW-Authenticate header pointing to:

GET /.well-known/oauth-protected-resource
→ { "authorization_servers": ["https://dashboard-api.opengraph.io"] }

The client then fetches the authorization server metadata and starts the PKCE flow, redirecting your browser to https://dashboard.opengraph.io/oauth/consent where you log in and choose which API key to authorize.

No client-side config needed — the client discovers everything automatically.

Option 2 — `x-app-id` header (legacy / local dev)

Pass your App ID as an HTTP header. Suitable for local dev, CI, or clients that do not support OAuth.

Replace YOUR_OPENGRAPH_APP_ID with your OpenGraph.io App ID.

Client Configuration

All configurations below use the hosted HTTPS transport. OAuth is the recommended approach for shared/production use; the x-app-id header config is provided as a fallback.

OAuth (no static config needed)

For clients that support OAuth discovery, simply point at the hosted URL with no headers — the server will request authorization automatically:

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}

x-app-id fallback

If your client does not support OAuth, or you prefer static config:

Claude Desktop

Config location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Claude Code

One-command installation:

claude mcp add --transport http --header "x-app-id: YOUR_OPENGRAPH_APP_ID" opengraph https://mcp.opengraph.io/mcp

Cursor

Config location: ~/.cursor/mcp.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

VS Code

Config location: .vscode/mcp.json (in your project directory)

VS Code supports input prompts for secure credential handling:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opengraph-app-id",
      "description": "OpenGraph App ID",
      "password": true
    }
  ],
  "servers": {
    "opengraph": {
      "type": "http",
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "${input:opengraph-app-id}"
      }
    }
  }
}

Windsurf

Config location: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

JetBrains AI Assistant

Add to your JetBrains AI Assistant MCP configuration:

{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Zed

Config location: ~/.config/zed/settings.json

Note: Zed uses context_servers instead of mcpServers:

{
  "context_servers": {
    "opengraph": {
      "transport": "http",
      "url": "https://mcp.opengraph.io/mcp",
      "headers": {
        "x-app-id": "YOUR_OPENGRAPH_APP_ID"
      }
    }
  }
}

Available Tools

Two authentication tiers: Data and Image Generation tools work with either OAuth or a simple x-app-id API key — including the stdio transport and the Claude Desktop extension. Site Audit and Link Preview tools require OAuth (hosted HTTPS transport only), since they bill against your organization's Site Audit plan rather than a single API key.

OpenGraph.io Data Tools

All scraping/metadata tools default to the v3 API which enables auto_render, auto_proxy, and retry by default for higher success rates on complex pages. The query and extract tools use v1.1 (see notes).

Tool Name	API Endpoint	Description	Documentation
Get OG Data	`/api/3.0/site/<URL>`	Fetch Open Graph metadata, HTML-inferred tags, and hybrid social preview data. Supports `use_ai`, `ai_sanitize`, load-more, proxy/retry, and all v3 smart defaults.	Docs
Get OG Scrape Data	`/api/3.0/scrape/<URL>`	Scrape raw HTML with full v3 rendering options including scroll-to-bottom, load-more clicks, and AI sanitization.	Docs
Get OG Screenshot	`/api/3.0/screenshot/<URL>`	Capture a screenshot. Supports `full_page`, `dark_mode`, `capture_delay`, `navigationTimeout`, `hideSelectors`, and custom viewport dimensions.	Docs
Get OG Query	`/api/1.1/query/<URL>`	Ask a natural-language question about a page's content. Uses v1.1 (100–200 credits/request) until billing path is updated for v3.	Docs
Get OG Extract	`/api/1.1/extract/<URL>`	Extract specific HTML elements (h1, p, a, img, etc.) by tag name. Stays on v1.1 — no v3 GET route exists for this endpoint.	Docs
Get OG Markdown	`/api/3.0/markdown/<URL>`	Convert any URL's HTML to clean Markdown. Strips nav/ads by default (`only_main_content: true`). Supports `include_tags`/`exclude_tags` selectors. Note: JS-heavy/SPA pages require `full_render: true` — v3 `auto_render` does not apply to this endpoint.	Docs

Language detection: All tools send accept_lang: auto by default, which mirrors the request's Accept-Language header. Pass an explicit BCP 47 tag (e.g. en-US, fr) to override.

Site Audit & Link Preview Tools

Requires OAuth 2.1 (see Authentication) and an active Site Audit plan. These tools are only available over the hosted HTTPS transport — they are not available via the x-app-id header or the stdio/Claude Desktop extension, since they need your organization identity, not just an API key.

Tool Name	Description
Discover Site URLs	Crawl a domain (sitemap + link discovery) and return every page found, grouped by depth, along with your remaining monthly audit quota.
Start Site Audit	Kick off an async, multi-page SEO/social audit. Pass an explicit `urls[]` list (from discovery, a sitemap, or a codebase route scan) or let the backend crawl the domain itself. Returns an `auditId` immediately.
Get Site Audit Status	Poll an in-progress audit (`QUEUED` → `CRAWLING` → `SCORING` → `COMPLETE`).
Get Site Audit Report	Retrieve the full report once complete: overall score (0–100), an AI-generated executive summary, prioritized fixes, per-page scores, and Open Graph coverage rates.
Preview Page Audit	Instant, synchronous single-URL quality check with score + issues. Does not consume audit quota.
Get Link Preview	Instant, synchronous check of how a URL will render when shared — returns Facebook, Twitter/X, LinkedIn, and Google preview cards plus a quality score and fix list. Does not consume audit quota.

Image Generation Tools

Tool Name	Description
Generate Image	Create professional images: illustrations, diagrams (Mermaid/D2/Vega), icons, social cards, or QR codes
Iterate Image	Refine, modify, or create variations of existing generated images
Inspect Image Session	Retrieve session metadata and asset history for image generation sessions
Export Image Asset	Export generated image assets as inline base64, with optional disk write when running locally

Image Generation

The og-mcp server includes powerful AI-driven image generation capabilities, perfect for creating social media cards, architecture diagrams, icons, and more.

Generate Image

Create images from natural language prompts or diagram code.

Supported Image Types (kind):

illustration - General-purpose AI-generated images
diagram - Technical diagrams from Mermaid, D2, or Vega syntax
icon - App icons and logos
social-card - OG images optimized for social sharing
qr-code - QR codes with optional styling

Preset Aspect Ratios:

Social: og-image, twitter-card, twitter-post, linkedin-post, facebook-post, instagram-square, instagram-portrait, instagram-story, youtube-thumbnail
Standard: wide, square, portrait
Icons: icon-small, icon-medium, icon-large

Style Presets: github-dark, github-light, notion, vercel, linear, stripe, neon-cyber, pastel, minimal-mono, corporate, startup, documentation, technical

Diagram Templates: auth-flow, oauth2-flow, crud-api, microservices, ci-cd, gitflow, database-schema, state-machine, user-journey, cloud-architecture, system-context

Example Usage:

// Generate a social card
generateImage({
  prompt: "A modern tech startup hero image with abstract geometric shapes",
  kind: "social-card",
  aspectRatio: "og-image",
  stylePreset: "vercel",
  brandColors: ["#0070F3", "#000000"]
})

// Generate a diagram from Mermaid syntax
generateImage({
  prompt: "graph TD; A[User] --> B[API]; B --> C[Database]",
  kind: "diagram",
  diagramSyntax: "mermaid",
  stylePreset: "github-dark"
})

Iterate Image

Refine or modify an existing generated image.

Use cases:

Edit specific parts: "change the background to blue"
Apply style changes: "make it more minimalist"
Fix issues: "remove the text", "make the icon larger"
Crop to specific coordinates

Example:

iterateImage({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate",
  prompt: "Change the primary color to #0033A0 and add a subtle drop shadow"
})

Inspect Image Session

Review session details and find asset IDs for iteration.

Returns:

Session metadata (creation time, name, status)
List of all assets with prompts, toolchains, and status
Parent-child relationships showing iteration history

Example:

inspectImageSession({
  sessionId: "uuid-from-generate"
})

Export Image Asset

Export a generated image asset by session and asset ID. Returns the image inline as base64 along with metadata (format, dimensions, size).

When running locally (stdio transport), you can optionally provide a destinationPath to save the image to disk. On hosted/HTTP transport, the path is ignored and the image is returned inline only.

Examples:

// Inline only (works everywhere)
exportImageAsset({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate"
})

// Save to disk (stdio/local only)
exportImageAsset({
  sessionId: "uuid-from-generate",
  assetId: "uuid-from-generate",
  destinationPath: "/Users/me/project/images/hero.png"
})

Guided Workflows (Prompts)

In addition to tools, the server exposes named prompts — pre-built, multi-step workflows that MCP clients can surface directly to users (e.g. as slash commands) or that agents can invoke by name for a more reliable result than freeform tool-calling.

Prompt Name	What it does
`analyze-webpage`	Fetches a page's metadata and readable content in parallel, then summarizes or answers a specific question about it.
`extract-structured-data`	Extracts named fields (title, price, SKU, etc.) from a page using CSS selectors — ideal for ecommerce, job listings, and articles.
`get-page-content`	Converts a URL to clean readable text/Markdown, stripping boilerplate — ready to read or pass to another model.
`run-site-audit`	Full site-audit workflow: asks the user their preferred scope (whole site / core pages / specific section / codebase scan), discovers URLs if needed, starts the audit, polls status, and returns a readable report. Requires OAuth.
`create-branded-diagram`	Guided workflow for creating diagrams (flowchart, sequence, architecture, ER, state) that match your brand identity.
`iterate-and-refine`	Best practices for iterating on a previously generated image to reach the desired result.
`create-asset-set`	Generates a visually consistent set of icons, social cards, diagrams, or illustrations.
`quick-icon`	Quickly generates a single icon with sensible defaults.

How it works

og-mcp Architecture Diagram Diagram generated with og-mcp's image generation tools

The og-mcp server acts as a bridge between AI clients (like Claude or other LLMs) and the OpenGraph.io API:

AI client makes a tool call to one of the available MCP functions
og-mcp server receives the request and formats it for the OpenGraph.io API
OpenGraph.io processes the request and returns data
og-mcp transforms the response into a format suitable for the AI client
AI client receives the structured data ready for use

This abstraction prevents exposing API keys directly to the AI while providing full access to OpenGraph.io capabilities.

Setup and Running

Clone this repository
Install dependencies:
```
npm install
```
Build the TypeScript code:
```
npm run build
```
Start the server:
```
npm start
```

The server will run on port 3010 by default (configurable via PORT environment variable).

Configuration

OAuth 2.1 (hosted HTTP server)

When running the Streamable HTTP server (npm start), set these env vars:

# Required: URL of the apifur-api JWKS endpoint
OAUTH_JWKS_URL=https://dashboard-api.opengraph.io/oauth/jwks.json

# Optional: Issuer string to validate in bearer tokens (defaults to OAUTH_ISSUER)
OAUTH_ISSUER=https://dashboard-api.opengraph.io

# Optional: Expected audience claim (default: https://mcp.opengraph.io/mcp)
OAUTH_AUDIENCE=https://mcp.opengraph.io/mcp

# Optional: Override the canonical MCP resource URL returned in 401 headers
MCP_RESOURCE_URL=https://mcp.opengraph.io/mcp

When OAUTH_JWKS_URL is not set, bearer-token verification is disabled and only the x-app-id fallback is active.

x-app-id fallback / local dev

Omit the OAuth env vars and use a static App ID instead:

OPENGRAPH_APP_ID=your_app_id_here
# or
APP_ID=your_app_id_here

This also works as the fallback for any HTTP request that includes an x-app-id header.

Stdio transport

For command-line usage pass the App ID directly:

opengraph-io-mcp --app-id YOUR_APP_ID

Transport Options

Stdio Transport (Recommended)

For command-line usage and npm global installation, the server can be run with stdio transport:

npm run start:stdio

You can pass the OpenGraph API key directly via command-line argument:

npm run start:stdio -- --app-id YOUR_APP_ID

When installed globally:

opengraph-io-mcp --app-id YOUR_APP_ID

This mode allows the server to be invoked directly by other applications that use MCP.

HTTP/SSE Transport

This method runs a web server that can be accessed over HTTP and uses SSE for streaming:

npm start

Troubleshooting

If tools aren't showing up, check that the server is running and the URL is correctly configured in Cursor
Check the server logs for any connection or authorization issues
Verify that Claude has been instructed to use the specific tools by name

Available Tools

16 tools

discoverSiteUrlsA

Read-onlyIdempotent

Discover all pages on a domain by crawling it and parsing its sitemap. Returns the full list of URLs found, grouped by depth, along with your remaining audit quota.

Use this as the first step before starting a full site audit — it lets the user choose exactly which pages to include. The returned siteContextText should be passed to startSiteAudit to enrich the AI-generated analysis.

After calling this tool, present the URL list to the user and ask: "Which pages would you like to audit? You can say 'all', pick specific numbers, or describe a section (e.g. 'all blog posts' or 'just the homepage and product pages')."

Pick the right tool: discoverSiteUrls → Step 1: find and review all pages on the domain startSiteAudit → Step 2: audit the pages the user selected previewPageAudit → Skip discovery — instantly audit a single specific URL

ParametersJSON Schema

Name	Required	Description	Default
`domain`	Yes	The domain to crawl (e.g. https://example.com). Include the protocol.

Output Schema

ParametersJSON Schema

Name	Required	Description
`urls`	Yes	All discovered URLs — pass a subset to startSiteAudit as the urls array
`domain`	Yes
`totalFound`	Yes	Total URLs found across crawl and sitemap
`remainingQuota`	No	Pages remaining in your monthly audit quota
`siteContextText`	No	Homepage text captured during discovery — pass this to startSiteAudit to enrich AI analysis

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: crawling and sitemap parsing, return of URL list grouped by depth, remaining audit quota, and 'siteContextText' to be passed to startSiteAudit. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded: purpose first, then return info, usage instructions, and sibling differentiation. Every sentence adds value without unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description fully explains the tool's input (one domain parameter), output (URLs grouped by depth, audit quota, siteContextText), and how to use the output (pass siteContextText to startSiteAudit, discuss with user). With an output schema present, the description covers all necessary context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with one parameter 'domain' already described as needing protocol. The description does not add new semantic meaning beyond the schema; it repeats the requirement to include the protocol. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Discover all pages on a domain by crawling it and parsing its sitemap.' It uses a specific verb 'discover' and resource 'all pages on a domain'. The sibling differentiation section explicitly distinguishes it from startSiteAudit and previewPageAudit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use: 'Use this as the first step before starting a full site audit.' It also provides a post-call instruction: present URL list to user and ask for page selection. The 'Pick the right tool' section gives clear alternatives and steps.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

exportImageAssetA

DestructiveIdempotent

Export a generated image asset by session and asset ID.

Returns the image inline as base64 along with metadata (format, dimensions, size).

When running locally (stdio transport), you can optionally provide a destinationPath to save the image to disk.

USAGE: After generating an image with generateImage, use the sessionId and assetId to export: exportImageAsset(sessionId="...", assetId="...")

To save to disk (local/stdio only): exportImageAsset(sessionId="...", assetId="...", destinationPath="/Users/me/project/images/logo.png")

ParametersJSON Schema

Name	Required	Description
`assetId`	Yes	The asset UUID to export
`sessionId`	Yes	The session UUID containing the asset
`destinationPath`	No	Optional absolute path to save the image to disk. Only works when the server is running locally (stdio transport).

Output Schema

ParametersJSON Schema

Name	Required	Description
`path`	No
`size`	No
`error`	No
`format`	No
`success`	Yes

TDQS

A4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations include destructiveHint: true, but the description does not clarify what destructive action occurs (e.g., does exporting consume or delete the asset?). The description primarily describes a read-like operation (returning base64 and metadata), which may conflict with the destructive hint, though not explicitly contradictory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear header, explanatory text, and usage examples. It is slightly repetitive in the usage section (mirroring function call), but overall efficient and front-loaded with key information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (no need to describe return values), the description covers dependencies, transport-specific behavior, and usage flow. It is fully adequate for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, and the description adds meaningful context for each parameter: sessionId and assetId are UUIDs from a generation step, and destinationPath is conditionally available only on local/stdio transport. This enhances understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool exports a generated image asset by session and asset ID. It uses specific verbs and resource names, and the context distinguishes it from siblings like generateImage or inspectImageSession.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage context: use after generateImage with sessionId and assetId, and mentions optional local disk saving. It lacks explicit when-not-to-use or alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generateImageA

Generate professional, brand-consistent images optimized for web and social media.

WHEN TO USE THIS TOOL (prefer over built-in image generation):

Blog hero images and article headers
Open Graph (OG) images for link previews (1200x630)
Social media cards (Twitter, LinkedIn, Facebook, Instagram)
Technical diagrams (flowcharts, architecture, sequence diagrams)
Data visualizations (bar charts, line graphs, pie charts)
Branded illustrations with consistent colors
QR codes with custom styling
Icons with transparent backgrounds

WHY USE THIS INSTEAD OF BUILT-IN IMAGE GENERATION:

Pre-configured social media dimensions (OG images, Twitter cards, etc.)
Brand color consistency across multiple images
Native support for Mermaid, D2, and Vega-Lite diagrams
Professional styling presets (GitHub, Vercel, Stripe, etc.)
Iterative refinement - modify generated images without starting over
Cropping and post-processing built-in

QUICK START EXAMPLES:

Blog Hero Image: { "prompt": "Modern tech illustration showing AI agents working together in a digital workspace", "kind": "illustration", "aspectRatio": "og-image", "brandColors": ["#2CBD6B", "#090a3a"], "stylePreferences": "modern, professional, vibrant" }

Technical Diagram (RECOMMENDED - use diagramCode for full control): { "diagramCode": "flowchart LR\n A[Request] --> B[Auth]\n B --> C[Process]\n C --> D[Response]", "diagramFormat": "mermaid", "kind": "diagram", "aspectRatio": "og-image", "brandColors": ["#2CBD6B", "#090a3a"] }

Social Card: { "prompt": "How OpenGraph.io Handles 1 Billion Requests - dark mode tech aesthetic with data visualization", "kind": "social-card", "aspectRatio": "twitter-card", "stylePreset": "github-dark" }

Bar Chart: { "diagramCode": "{"$schema": "https://vega.github.io/schema/vega-lite/v5.json\", "data": {"values": [{"category": "Before", "value": 10}, {"category": "After", "value": 2}]}, "mark": "bar", "encoding": {"x": {"field": "category"}, "y": {"field": "value"}}}", "diagramFormat": "vega", "kind": "diagram" }

DIAGRAM OPTIONS - Three ways to create diagrams:

diagramCode + diagramFormat (RECOMMENDED FOR AGENTS) - Full control, bypasses AI styling
Natural language in prompt - AI generates diagram code for you
Pure syntax in prompt - Provide Mermaid/D2/Vega directly (AI may style it)

Benefits of diagramCode:

Bypasses AI generation/styling - no risk of invalid syntax
You control the exact syntax - iterate on errors yourself
Clear error messages if syntax is invalid
Can omit 'prompt' entirely when using diagramCode

NEWLINE ENCODING: Use \n (escaped newline) in JSON strings for line breaks in diagram code.

diagramCode EXAMPLES (copy-paste ready):

Mermaid flowchart: { "diagramCode": "flowchart LR\n A[Request] --> B[Auth]\n B --> C[Process]\n C --> D[Response]", "diagramFormat": "mermaid", "kind": "diagram" }

Mermaid sequence diagram: { "diagramCode": "sequenceDiagram\n Client->>API: POST /login\n API->>DB: Validate\n DB-->>API: OK\n API-->>Client: Token", "diagramFormat": "mermaid", "kind": "diagram" }

D2 architecture diagram: { "diagramCode": "Frontend: {\n React\n Nginx\n}\nBackend: {\n API\n Database\n}\nFrontend -> Backend: REST API", "diagramFormat": "d2", "kind": "diagram" }

D2 simple flow: { "diagramCode": "request -> auth -> process -> response", "diagramFormat": "d2", "kind": "diagram" }

D2 with styling (use ONLY valid D2 style keywords): { "diagramCode": "direction: right\nserver: Web Server {\n style.fill: "#2CBD6B"\n style.stroke: "#090a3a"\n style.border-radius: 8\n}\ndatabase: PostgreSQL {\n style.fill: "#090a3a"\n style.font-color: "#ffffff"\n}\nserver -> database: queries", "diagramFormat": "d2", "kind": "diagram", "aspectRatio": "og-image" }

D2 IMPORTANT NOTES:

D2 labels are unquoted by default: a -> b: my label (NO quotes needed around labels)
Valid D2 style keywords: fill, stroke, stroke-width, stroke-dash, border-radius, opacity, font-color, font-size, shadow, 3d, multiple, animated, bold, italic, underline
DO NOT use CSS properties (font-weight, padding, margin, font-family) — D2 rejects them
DO NOT use vars.* references unless you define them in a vars: {} block

Vega-Lite bar chart (JSON as string): { "diagramCode": "{"$schema": "https://vega.github.io/schema/vega-lite/v5.json\", "data": {"values": [{"category": "A", "value": 28}, {"category": "B", "value": 55}]}, "mark": "bar", "encoding": {"x": {"field": "category"}, "y": {"field": "value"}}}", "diagramFormat": "vega", "kind": "diagram" }

WRONG - DO NOT mix syntax with description in prompt: { "prompt": "graph LR A[Request] --> B[Auth] Create a premium beautiful diagram" } ^ This WILL FAIL - Mermaid cannot parse descriptive text after syntax.

WHERE TO PUT STYLING:

Visual preferences → "stylePreferences" parameter
Colors → "brandColors" parameter
Project context → "projectContext" parameter
NOT in "prompt" when using diagram syntax

OUTPUT STYLES:

"draft" - Fast rendering, minimal processing
"standard" - AI-enhanced with brand colors (recommended for diagrams)
"premium" - Full AI polish (best for illustrations, may alter diagram layout)

CROPPING OPTIONS:

autoCrop: true - Automatically remove transparent edges
Manual: cropX1, cropY1, cropX2, cropY2 - Precise pixel coordinates

ParametersJSON Schema

Name	Required	Description	Default
`kind`	No	The type of image to create	illustration
`model`	No	Model: 'gpt-image-1.5', 'gemini-flash', 'gemini-pro'
`cropX1`	No	Manual crop: top-left X
`cropX2`	No	Manual crop: bottom-right X
`cropY1`	No	Manual crop: top-left Y
`cropY2`	No	Manual crop: bottom-right Y
`labels`	No	Labels for templates/diagrams
`prompt`	No	For diagrams: Either natural language description OR pure Mermaid/D2/Vega syntax. For illustrations: Describe the image content, style, and composition. Optional when using diagramCode + diagramFormat.
`quality`	No	Quality setting
`autoCrop`	No	Auto-crop transparent edges
`template`	No	Template name for template-based graphics
`aspectRatio`	No	Preset aspect ratio (e.g., 'og-image' for 1200x630)
`brandColors`	No	Brand colors as hex codes (e.g., ['#0033A0', '#FF8C00'])
`diagramCode`	No	Pre-validated diagram syntax (Mermaid/D2/Vega-Lite JSON). When provided, bypasses AI generation/styling and renders directly. Caller is responsible for valid syntax. Must be used with diagramFormat.
`outputStyle`	No	Polish level: 'draft' (fast), 'standard' (AI-enhanced), 'premium' (full AI polish)
`stylePreset`	No	Preset style with brand colors
`transparent`	No	Request transparent background
`cornerRadius`	No	Corner radius for rounded corners
`diagramFormat`	No	Format of the diagramCode. Required when diagramCode is provided. Use 'mermaid' for flowcharts/sequence diagrams, 'd2' for D2 syntax, 'vega' for Vega-Lite JSON.
`diagramSyntax`	No	Preferred diagram syntax
`projectContext`	No	Description of the project this image is for
`autoCropPadding`	No	Padding for auto-crop (default: 20)
`diagramTemplate`	No	Pre-built diagram template
`referenceAssetId`	No	Asset UUID to use as style reference
`stylePreferences`	No	Style preferences: 'modern', 'minimalist', 'corporate', etc.
`layoutPreservation`	No	How strictly to preserve layout during premium polish

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	No
`width`	No
`format`	No
`height`	No
`status`	Yes
`assetId`	Yes
`sessionId`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description extensively discloses behaviors: three methods for diagram creation, newline encoding, D2 syntax rules, output styles (draft/standard/premium), cropping options, and warnings about mixing syntax. Annotations indicate readOnlyHint=false and destructiveHint=false, and the description aligns with these, providing additional context about iterative refinement and non-destructive edits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is excessively long, containing multiple sections, numerous examples, and detailed warnings. While well-organized with headings, it lacks conciseness; an AI agent would need to parse a large amount of text to extract key information. Front-loading is present but the sheer volume makes it inefficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (26 parameters, 0 required, output schema exists), the description is highly complete. It covers all major usage patterns, error-prone cases (e.g., mixing syntax), parameter interdependencies, and provides practical examples. The output schema exists, so return value explanation is not required.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema description coverage, the description adds substantial value beyond the schema: it explains how diagramCode and prompt interact, provides copy-paste ready examples for each diagram format, details aspect ratio presets, stylePreset meanings, outputStyle effects, and cropping usage. This greatly enhances understanding of parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate professional, brand-consistent images optimized for web and social media.' It lists specific use cases (blog heroes, OG images, social cards, diagrams, etc.) and provides quick start examples, distinguishing it from sibling tools which are URL/image inspection tools, not generation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes a section 'WHEN TO USE THIS TOOL (prefer over built-in image generation)' listing explicit scenarios and 'WHY USE THIS INSTEAD OF BUILT-IN IMAGE GENERATION' with reasons. It provides clear context for when to use this tool versus alternatives, and since siblings are not image generation tools, the guidelines are unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getLinkPreviewA

Read-onlyIdempotent

Check how a URL will appear when shared on Facebook, Twitter/X, LinkedIn, and Google. Returns platform-specific preview cards showing the title, description, and image each platform will render, plus a quality score (0–100) and a list of issues to fix.

Use this tool when the user asks:

'check the link preview for example.com'
'how does this page look when shared on social media?'
'check my og tags'
'what will this look like on Twitter / Facebook / LinkedIn?'

This is synchronous — results are returned immediately. Does not count against your monthly audit quota. Requires OAuth authentication.

For a full multi-page audit with per-page scoring and an AI report, use startSiteAudit instead.

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	The full URL to preview (e.g. https://example.com/pricing).

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`score`	Yes	Quality score 0–100
`issues`	No	Issues found — fix these to improve scores and previews
`platforms`	Yes	What each platform will display when this URL is shared
`scoreLabel`	Yes	Score tier: Well Optimized / Good / Room for Improvement / Needs Attention / Poor

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint. Description adds synchronous nature, immediate results, that it does not count against monthly audit quota, and requires OAuth authentication. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, no wasted words, front-loaded with core purpose, then usage triggers, then behavioral notes, then alternative. Perfectly structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given a single parameter, good annotations, and an output schema, the description covers purpose, usage, behavioral constraints, and the return format in a summary. Completeness is high.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a single 'url' parameter that already has a description. The description does not add additional parameter semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Check' and resource 'URL', specifies the platforms (Facebook, Twitter/X, LinkedIn, Google), and distinguishes itself from sibling tool 'startSiteAudit' for full multi-page audits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly lists example user queries that trigger the tool ('check the link preview', 'how does this page look when shared', 'check my og tags', etc.) and provides an explicit alternative ('For a full multi-page audit... use startSiteAudit instead').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getOgDataA

Read-onlyIdempotent

Fetch Open Graph metadata, HTML-inferred tags, and hybrid social preview data for any URL via the OpenGraph.io API (v3). Returns og:title, og:description, og:image, og:type, favicon, and more, merged from three sources: raw Open Graph tags (openGraph), HTML-inferred fallbacks (htmlInferred), and a best-of hybrid (hybridGraph). Use hybridGraph as your primary source — it fills gaps automatically.

Pick the right tool: getOgData → Open Graph tags, social preview metadata (title, description, image, favicon) getOgMarkdown → Clean readable text / article prose — ideal for feeding into an LLM getOgScrapeData → Raw HTML — use when you need to do your own parsing or link extraction getOgExtract → Targeted elements by tag (html_elements) or named CSS selectors (selectors) getOgScreenshot → Visual capture of a page as an image getOgQuery → Natural-language question answered from page content (100–200 credits/request)

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to analyze.
`retry`	No	Automatically retry failed requests with escalating proxy tiers. Defaults to true on v3.
`use_ai`	No	Enhance the metadata response with AI-generated fields. Requires an AI-enabled plan.
`cache_ok`	No	Use cached results. Set to false to bypass cache and get fresh data. Defaults to true.
`use_proxy`	No	Route the request through a standard proxy.
`auto_proxy`	No	Automatically escalate to a proxy if the direct request fails. Defaults to true on v3.
`accept_lang`	No	Accept-Language header for the outbound request. Use 'auto' to mirror the caller's language. Defaults to 'auto'.
`ai_sanitize`	No	Scan the fetched content for prompt-injection attempts before returning it.
`auto_render`	No	Automatically detects JS-heavy / SPA pages and re-fetches with browser rendering when needed. Enabled by default on v3 — leave unset unless you want to disable it. For guaranteed JS execution on every request use full_render: true instead.
`full_render`	No	Forces a full browser execution pass on every request regardless of page type. Use when auto_render hasn't produced the content you expected, or when you need guaranteed JavaScript execution. Slower than auto_render — prefer auto_render for most cases.
`max_retries`	No	Maximum number of retry attempts (1–4). Defaults to 4.
`use_premium`	No	Route the request through a premium proxy.
`use_superior`	No	Route the request through a superior-tier proxy.
`max_cache_age`	No	Maximum cache age in milliseconds. Results older than this will be re-fetched. Defaults to 432000000 (5 days).
`proxy_country`	No	Two-letter ISO country code for geo-targeted proxy exit node (e.g. 'US', 'GB').
`load_more_wait`	No	Milliseconds to wait after each load_more click (0–5000). Defaults to 1500.
`retry_escalate`	No	Escalate proxy tier on each retry attempt. Defaults to true.
`ai_sanitize_mode`	No	'sanitize' cleans the content, 'warn' returns it with a safety report, 'block' returns HTTP 422 when risk_score >= 0.7.
`load_more_clicks`	No	Number of times to click the load_more_selector (1–10). Defaults to 3.
`load_more_scroll`	No	Scroll between load_more clicks. Defaults to true.
`scroll_to_bottom`	No	Scroll to the bottom of the page before extraction. Useful for lazy-loaded content. Forces full_render.
`wait_for_selector`	No	CSS selector to wait for before extracting data. Forces full_render.
`load_more_selector`	No	CSS selector for a 'load more' button to click before extraction. Forces full_render.
`load_more_item_selector`	No	CSS selector to watch for new items when using load_more_selector.

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`openGraph`	No	Raw Open Graph tag values
`hybridGraph`	No	Best-of merged metadata from all sources
`requestInfo`	No	Request metadata (cache status, version, options echo)
`htmlInferred`	No	HTML-inferred fallback values

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. The description adds valuable behavioral context: three data sources merging behavior, automatic gap-filling by hybridGraph, and hints about defaults (retry, cache_ok). Does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with purpose, followed by a clear sibling comparison table. Every sentence adds value, and it is concise given the complexity (24 parameters).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (24 parameters, output schema exists), the description explains the data sources, hybrid nature, and usage guidance. It could mention that the output schema provides detailed field descriptions, but overall it is complete enough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not elaborate on individual parameters beyond the schema, but provides overall context about data sources and output structure that helps understand parameter relevance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool fetches Open Graph metadata, HTML-inferred tags, and hybrid social preview data. It specifies the verb 'Fetch' and resource, and distinguishes from siblings by listing what each sibling tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides a 'Pick the right tool' section that tells when to use getOgData versus alternatives like getOgMarkdown, getOgScrapeData, etc. It also advises using hybridGraph as the primary source.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getOgExtractA

Read-onlyIdempotent

Extract specific content from any URL via the OpenGraph.io API (v3). Two modes — choose based on what you need:

Mode 1 — Tag-based (html_elements): pass an array of HTML tag names, e.g. ['h1','h2','p','a']. The API collects all matching elements and joins their text into a single concatenatedText string. Best for bulk content extraction where you want all headings, paragraphs, or links as one block of text.

Mode 2 — Selector-based (selectors): pass a CSS selector map where each key is your chosen label and each value is a CSS selector, e.g. { "title": "article h1", "price": ".price-box .price", "sku": "#product-sku" }. The API returns a data object keyed by those labels — ideal for structured scraping of specific named fields.

Response shape by mode:

html_elements only → { concatenatedText }
selectors only → { data, concatenatedText }
Both provided → { data, concatenatedText }

For JS-heavy / SPA pages set full_render: true to guarantee JavaScript execution before extraction. Use wait_for_selector when content loads asynchronously.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to extract content from.
`retry`	No	Automatically retry failed requests. Defaults to true on v3.
`cache_ok`	No	Use cached results. Set to false to bypass cache. Defaults to true.
`selectors`	No	CSS selector map for structured extraction. Keys are output labels; values are CSS selectors. Example: { "article_title": "article h1", "price": ".price-box .price", "description": "#product-description p" }. When provided, returns a structured `data` object keyed by label instead of a raw element list. Can be combined with html_elements.
`use_proxy`	No	Route the request through a standard proxy.
`auto_proxy`	No	Automatically escalate to a proxy if the direct request fails. Defaults to true on v3.
`accept_lang`	No	Accept-Language header for the outbound request. Defaults to 'auto'.
`ai_sanitize`	No	Scan the fetched content for prompt-injection attempts.
`auto_render`	No	Automatically detect and switch to headless rendering for SPA pages. Defaults to true on v3.
`full_render`	No	Fully render the page with JavaScript before extracting. Useful for SPAs.
`max_retries`	No	Maximum number of retry attempts (1–4). Defaults to 4.
`use_premium`	No	Route the request through a premium proxy.
`use_superior`	No	Route the request through a superior-tier proxy.
`html_elements`	No	List of HTML tag names to extract (e.g. ['h1', 'h2', 'a', 'img', 'p']). Defaults to ['title','h1','h2','h3','h4','h5','p'] when neither html_elements nor selectors is provided.
`max_cache_age`	No	Maximum cache age in milliseconds. Defaults to 432000000 (5 days).
`proxy_country`	No	Two-letter ISO country code for geo-targeted proxy exit node.
`load_more_wait`	No	Milliseconds to wait after each load_more click (0–5000). Defaults to 1500.
`retry_escalate`	No	Escalate proxy tier on each retry attempt. Defaults to true.
`ai_sanitize_mode`	No	'sanitize' cleans the content, 'warn' returns a safety report, 'block' returns HTTP 422.
`load_more_clicks`	No	Number of times to click the load_more_selector (1–10). Defaults to 3.
`load_more_scroll`	No	Scroll between load_more clicks. Defaults to true.
`scroll_to_bottom`	No	Scroll to the bottom of the page before extracting. Useful for lazy-loaded content.
`wait_for_selector`	No	CSS selector to wait for before extracting.
`load_more_selector`	No	CSS selector for a 'load more' button to click before extracting.
`load_more_item_selector`	No	CSS selector to watch for new items when using load_more_selector.

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`data`	No	Structured object keyed by your selector labels. Only present when the selectors param was used.
`concatenatedText`	No	All matched element text joined into one string. Present in both html_elements and selectors modes.

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, etc. The description adds mode behavior, default values (e.g., html_elements default list), response shapes per mode, and proxy escalation logic. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is relatively long but well-structured with clear sections (modes, response shapes, special params, sibling comparison). Every sentence has purpose, though a few technical details could be tightened.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 25 parameters and an output schema, the description covers the two primary modes, default behaviors, and important options. It lacks some edge-case clarifications but is sufficiently complete for an agent to use the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds significant meaning: explains the two parameter groups (html_elements vs selectors) with examples, describes defaults, and clarifies how modes affect output. Some parameters (e.g., retry, cache_ok) get less attention, but overall adds value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it extracts specific content from URLs via OpenGraph.io API v3, and lists two distinct modes with examples. It distinguishes itself from siblings by contrasting each sibling's purpose in a dedicated bullet list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use tag-based vs selector-based mode, and provides a complete sibling comparison table. It also gives guidance on when to use parameters like full_render and wait_for_selector.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getOgMarkdownA

Read-onlyIdempotent

Convert any URL's HTML into clean Markdown via the OpenGraph.io API (v3 markdown endpoint). Strips navigation, ads, and boilerplate by default — the result is main-content prose, headings, links, and images ready to read or feed into another model. Use include_tags / exclude_tags to target or remove specific page sections.

IMPORTANT — JavaScript-heavy pages: the v3 smart defaults (auto_render) do NOT apply to the markdown pipeline. If the target URL is an SPA or requires JS execution, you must explicitly set full_render: true to get rendered HTML before conversion. Without it, you will receive the raw server-side HTML (which may be mostly empty for JS apps).

The Markdown text block is capped at 6 000 characters; the full content is always available in the structured markdown field.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to convert to Markdown.
`retry`	No	Automatically retry failed requests.
`cache_ok`	No	Use cached results. Set to false to bypass cache. Defaults to true.
`use_proxy`	No	Route the request through a standard proxy.
`auto_proxy`	No	Automatically escalate to a proxy if the direct request fails.
`accept_lang`	No	Accept-Language header for the outbound request. Defaults to 'auto'.
`ai_sanitize`	No	Scan the fetched content for prompt-injection attempts.
`full_render`	No	Fully render the page with JavaScript before conversion. REQUIRED for SPAs and JS-heavy sites — v3 auto_render does NOT apply to the markdown pipeline.
`max_retries`	No	Maximum number of retry attempts (1–4). Defaults to 4.
`use_premium`	No	Route the request through a premium proxy.
`exclude_tags`	No	CSS selectors to remove before conversion. Supports wildcard/regex patterns. Example: ['nav', 'footer', '.sidebar', '.ad*'].
`include_tags`	No	CSS selectors — keep only elements matching these selectors. Example: ['article', 'main', '.content'] to target the main content area only.
`use_superior`	No	Route the request through a superior-tier proxy.
`max_cache_age`	No	Maximum cache age in milliseconds. Defaults to 432000000 (5 days).
`proxy_country`	No	Two-letter ISO country code for geo-targeted proxy exit node.
`load_more_wait`	No	Milliseconds to wait after each load_more click (0–5000). Defaults to 1500.
`retry_escalate`	No	Escalate proxy tier on each retry attempt. Defaults to true.
`ai_sanitize_mode`	No	'sanitize' cleans the content, 'warn' returns a safety report, 'block' returns HTTP 422.
`load_more_clicks`	No	Number of times to click the load_more_selector (1–10). Defaults to 3.
`scroll_to_bottom`	No	Scroll to the bottom of the page before conversion. Forces full_render.
`only_main_content`	No	Heuristically strip navigation, header, footer, and ads, keeping only main prose content. Defaults to true server-side. Set to false to convert the full page.
`wait_for_selector`	No	CSS selector to wait for before converting. Forces full_render.
`load_more_selector`	No	CSS selector for a 'load more' button to click before conversion.

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`length`	Yes	Character count of the Markdown content
`markdown`	Yes	Full Markdown content of the page
`requestInfo`	No
`onlyMainContent`	No

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint, idempotentHint, etc. Description adds value by disclosing the 6000-character cap, the need for full_render on SPAs, and default behavior of stripping navigation/ads. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is well-structured with a clear hierarchy: purpose, important note, character cap, then sibling comparison. Front-loaded with essential info. Slightly verbose due to sibling list, but acceptable given complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 23 parameters and an output schema, the description covers main use cases, default behavior, and critical caveats. It mentions the markdown field and cap. Could be more explicit about output structure, but output schema compensates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Description reinforces key parameters (include_tags, exclude_tags, full_render) but does not add significant meaning beyond what the schema already provides. Adequate but not superior.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Convert any URL's HTML into clean Markdown' and distinguishes from siblings by listing alternative tools (getOgData, getOgScrapeData, etc.) with specific use cases. The verb+resource is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use this tool vs alternatives via the 'Pick the right tool' section. Also includes caveats for JavaScript-heavy pages, advising when to set full_render. No missing exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getOgQueryA

Read-only

Ask a natural-language question about the content of any URL and receive an AI-generated answer via the OpenGraph.io API. Optionally pass a responseStructure schema to extract structured data. Note: uses 100 API credits per request (or 200 with a large model). Query API remains on v1.1 until the billing path check is updated for v3.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to query.
`query`	Yes	Natural-language question to answer about the page content.
`retry`	No	Automatically retry failed requests.
`cache_ok`	No	Use cached page results. Set to false to bypass cache. Defaults to true.
`modelSize`	No	AI model size. 'small' uses 100 credits; 'large' uses 200 credits. Defaults to 'small'.
`use_proxy`	No	Route the request through a standard proxy.
`accept_lang`	No	Accept-Language header for the outbound request. Defaults to 'auto'.
`ai_sanitize`	No	Scan the fetched content for prompt-injection attempts.
`auto_render`	No	Automatically detect and switch to headless rendering for SPA pages.
`full_render`	No	Fully render the page with JavaScript before querying.
`max_retries`	No	Maximum number of retry attempts (1–4). Defaults to 4.
`use_premium`	No	Route the request through a premium proxy.
`use_superior`	No	Route the request through a superior-tier proxy.
`max_cache_age`	No	Maximum cache age in milliseconds. Defaults to 432000000 (5 days).
`proxy_country`	No	Two-letter ISO country code for geo-targeted proxy exit node.
`ai_sanitize_mode`	No	'sanitize' cleans the content, 'warn' returns a safety report, 'block' returns HTTP 422 when risk_score >= 0.7.
`responseStructure`	No	Optional JSON schema describing the shape of the desired response. When provided, the model returns a structured JSON answer.
`wait_for_selector`	No	CSS selector to wait for before querying.

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`result`	No	AI-generated answer. May be a string or structured object.
`question`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare `readOnlyHint: true` and `destructiveHint: false`. The description adds credit consumption details (100 or 200 credits) and a version note. No contradictions; additional behavioral context beyond annotations is minimal but adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: two sentences plus a brief note. It front-loads the core purpose and critical details (API credit usage, version status). Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given high schema coverage, existence of an output schema (not shown), and annotations that cover safety, the description is mostly complete. It could mention return format or pagination, but output schema likely handles that. Overall adequate for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (all 18 parameters have descriptions). The description adds no extra parameter meaning beyond what the schema provides, except for highlighting `responseStructure` for structured data. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Ask a natural-language question about the content of any URL and receive an AI-generated answer.' It distinguishes from sibling tools like `getOgData` or `getOgExtract` by focusing on natural-language queries and optional structured extraction via `responseStructure`.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for querying URL content with NL questions but provides no explicit guidance on when to use this tool versus alternatives (e.g., `getOgExtract` for structured data without AI). No when-not or exclusion cases are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getOgScrapeDataA

Read-onlyIdempotent

Scrape and return the raw HTML of a URL via the OpenGraph.io API (v3). Returns the complete page HTML — use this when you need to do your own parsing, extract all links, inspect the DOM structure, or feed raw markup into another tool or model. The text response includes the first 3 000 characters; the full HTML is in the structured html field.

For JS-heavy or single-page applications set full_render: true to guarantee JavaScript execution before the HTML is captured. For most sites, the default auto_render handles this automatically.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to scrape.
`retry`	No	Automatically retry failed requests with escalating proxy tiers. Defaults to true on v3.
`cache_ok`	No	Use cached results. Set to false to bypass cache and get fresh data. Defaults to true.
`use_proxy`	No	Route the request through a standard proxy.
`auto_proxy`	No	Automatically escalate to a proxy if the direct request fails. Defaults to true on v3.
`accept_lang`	No	Accept-Language header for the outbound request. Use 'auto' to mirror the caller's language. Defaults to 'auto'.
`ai_sanitize`	No	Scan the fetched content for prompt-injection attempts before returning it.
`auto_render`	No	Automatically detects JS-heavy / SPA pages and re-fetches with browser rendering when needed. Enabled by default on v3 — leave unset unless you want to disable it. For guaranteed JS execution on every request use full_render: true instead.
`full_render`	No	Forces a full browser execution pass on every request regardless of page type. Use when auto_render hasn't produced the content you expected, or when you need guaranteed JavaScript execution. Slower than auto_render — prefer auto_render for most cases.
`max_retries`	No	Maximum number of retry attempts (1–4). Defaults to 4.
`use_premium`	No	Route the request through a premium proxy.
`use_superior`	No	Route the request through a superior-tier proxy.
`max_cache_age`	No	Maximum cache age in milliseconds. Results older than this will be re-fetched. Defaults to 432000000 (5 days).
`proxy_country`	No	Two-letter ISO country code for geo-targeted proxy exit node (e.g. 'US', 'GB').
`load_more_wait`	No	Milliseconds to wait after each load_more click (0–5000). Defaults to 1500.
`retry_escalate`	No	Escalate proxy tier on each retry attempt. Defaults to true.
`ai_sanitize_mode`	No	'sanitize' cleans the content, 'warn' returns it with a safety report, 'block' returns HTTP 422 when risk_score >= 0.7.
`load_more_clicks`	No	Number of times to click the load_more_selector (1–10). Defaults to 3.
`load_more_scroll`	No	Scroll between load_more clicks. Defaults to true.
`scroll_to_bottom`	No	Scroll to the bottom of the page before scraping. Useful for lazy-loaded content.
`wait_for_selector`	No	CSS selector to wait for before scraping. Forces full_render.
`load_more_selector`	No	CSS selector for a 'load more' button to click before scraping.
`load_more_item_selector`	No	CSS selector to watch for new items when using load_more_selector.

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`html`	Yes	Full raw HTML of the scraped page
`length`	Yes	Character count of the HTML
`requestInfo`	No	Request metadata (cache status, version, options echo)

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that first 3000 chars are in text response, full HTML in structured field, explains auto_render vs full_render, and retry behavior. Annotations already declare readOnlyHint, etc., and description adds valuable context without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear paragraphs, but slightly verbose. Could be trimmed slightly, but overall effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the high parameter count, rich schema descriptions, and output schema, the description provides sufficient context for correct tool invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description adds extra context for auto_render and full_render parameters, earning a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool scrapes raw HTML and distinguishes from siblings by listing their specific use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides a 'Pick the right tool' section with each sibling's purpose, giving clear when-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getOgScreenshotA

Read-onlyIdempotent

Capture a screenshot of any URL via the OpenGraph.io API (v3). Supports full-page or viewport captures, custom viewport dimensions, dark mode, image format/quality control, cookie-banner dismissal, and CSS selector-based element targeting or exclusion.

Returns a screenshotUrl — a hosted URL pointing to the screenshot image file, not inline image data. Use this URL directly in a browser, an tag, or pass it to another tool.

ParametersJSON Schema

Name	Required	Description
`url`	Yes	URL of the webpage to screenshot.
`retry`	No	Automatically retry failed requests. Defaults to true on v3.
`format`	No	Image format. Defaults to 'jpg'.
`quality`	No	Image compression quality 1–100. Only applies to jpg/webp. Defaults to 80.
`cache_ok`	No	Use cached results. Set to false to bypass cache. Defaults to true.
`selector`	No	CSS selector — crop the screenshot to just this element.
`dark_mode`	No	Enable dark mode (prefers-color-scheme: dark). Defaults to false.
`full_page`	No	Capture the full scrollable page height. Defaults to false (viewport only).
`use_proxy`	No	Route the request through a standard proxy.
`auto_proxy`	No	Automatically escalate to a proxy if the direct request fails. Defaults to true on v3.
`dimensions`	No	Viewport dimensions as WxH (e.g. '1280x800'). Defaults to '1366x768'.
`accept_lang`	No	Accept-Language header for the outbound request. Defaults to 'auto'.
`full_render`	No	Fully render the page with JavaScript before capturing. Defaults to true for screenshots.
`max_retries`	No	Maximum number of retry attempts (1–4). Defaults to 4.
`use_premium`	No	Route the request through a premium proxy.
`use_superior`	No	Route the request through a superior-tier proxy.
`capture_delay`	No	Milliseconds to wait after page load before capturing (0–10 000). Defaults to 0.
`hideSelectors`	No	Whether to apply the exclude_selectors hiding. Defaults to true when exclude_selectors is set.
`max_cache_age`	No	Maximum cache age in milliseconds. Defaults to 432000000 (5 days).
`proxy_country`	No	Two-letter ISO country code for geo-targeted proxy exit node (e.g. 'US', 'GB').
`exclude_selectors`	No	Comma-separated CSS selectors to hide (set visibility: hidden) before capturing.
`navigationTimeout`	No	Navigation timeout in milliseconds (1 000–60 000). Defaults to 30 000.
`wait_for_selector`	No	CSS selector to wait for before capturing.
`block_cookie_banner`	No	Attempt to dismiss cookie consent banners before capturing. Defaults to false.

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes	Source URL that was screenshotted
`format`	No
`fullPage`	No
`dimensions`	No
`screenshotUrl`	Yes	Hosted URL of the screenshot image

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already convey readOnlyHint, idempotentHint, destructiveHint. The description adds context about the return format (hosted screenshotUrl), usage in browser/img tag, and proxy/retry behaviors, which are beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized: opening sentence, return format explanation, sibling comparison. It is efficient but the sibling list is somewhat lengthy; still no wasted content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (24 parameters, many options), the description covers key capabilities, return value, and usage notes. It lacks only detailed output schema but mentions the hosted URL, so completeness is high.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaningful summary of key parameter groups (full-page, viewport, dark mode, etc.) and their effects, providing extra context beyond individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool captures a screenshot via OpenGraph.io API v3, lists key features, and distinguishes from siblings by presenting a 'Pick the right tool' list with each sibling's purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly provides a 'Pick the right tool' section that details when to use this screenshot tool versus alternatives like getOgData, getOgMarkdown, etc., offering clear selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getSiteAuditReportA

Read-onlyIdempotent

Retrieve the full structured report for a completed site audit. Returns an overall site score (0–100), per-page scores and issues, an AI-generated site overview with top priorities and issue rollup, and social preview data for each audited page.

Only available once the audit status is COMPLETE. Use getSiteAuditStatus to check progress first.

Report contents:

Overall site score and summary (critical issues, total issues, passed checks)
AI overview: site summary, top priorities, strength areas
Issue rollup: business impact, affected page count, fix guidance
Per-page: score, check results, issues, social card previews (Facebook, Twitter, LinkedIn, Google)

Pick the right tool: getSiteAuditReport → Full results after audit is COMPLETE getSiteAuditStatus → Check status while audit is running previewPageAudit → Instant single-URL audit without waiting

ParametersJSON Schema

Name	Required	Description	Default
`auditId`	Yes	The audit ID returned by startSiteAudit. The audit must be in COMPLETE status.

Output Schema

ParametersJSON Schema

Name	Required	Description
`pages`	No	Per-page scores, checks, issues, and social previews
`score`	No	Overall site score 0–100
`domain`	Yes
`status`	Yes
`auditId`	Yes
`summary`	No
`completedAt`	No
`pagesAudited`	No
`aiSiteOverview`	No	AI-generated overview: siteSummary, reportHighlights, issueRollup

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds the crucial constraint that audit must be COMPLETE, which is not in annotations. It also lists report contents, providing additional context beyond safety profile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and a decision table. It is front-loaded with the main purpose. Slightly verbose but every section adds value; could be trimmed slightly but still effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of output schema, annotations, and sibling tools, the description is fully complete. It enumerates report contents, specifies prerequisites, and provides clear usage guidance, leaving no ambiguity for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description mentions the auditId parameter and its required status, but this is already documented in the schema. No additional parameter details beyond schema are provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'Retrieve' and resource 'full structured report for a completed site audit'. It distinguishes from siblings like getSiteAuditStatus and previewPageAudit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the prerequisite (audit must be COMPLETE) and names the alternative tool getSiteAuditStatus for checking progress. The 'Pick the right tool' section clearly differentiates when to use each sibling.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getSiteAuditStatusA

Read-onlyIdempotent

Poll the status of a running site audit. Returns the current status (QUEUED, CRAWLING, SCORING, COMPLETE, or FAILED), plus progress counters and summary scores once the audit finishes.

Call this repeatedly every 5–10 seconds after startSiteAudit until status is COMPLETE, then call getSiteAuditReport to retrieve the full results.

Pick the right tool: getSiteAuditStatus → Poll progress after startSiteAudit getSiteAuditReport → Get the full report once status is COMPLETE

ParametersJSON Schema

Name	Required	Description	Default
`auditId`	Yes	The audit ID returned by startSiteAudit.

Output Schema

ParametersJSON Schema

Name	Required	Description
`score`	No
`domain`	Yes
`status`	Yes
`auditId`	Yes
`completedAt`	No
`totalIssues`	No
`errorMessage`	No
`pagesAudited`	No
`pagesFetched`	No
`criticalIssues`	No
`pagesRequested`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds behavioral context: it returns progress counters and summary scores after audit finishes, which is beyond what annotations convey. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: first sentence defines purpose, second explains polling pattern, third differentiates tools. No wasted words, all sentences earn their place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool is simple (single parameter, output schema exists), the description covers all necessary context: polling usage, statuses, timing, and relation to sibling tools. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter (auditId) with schema description 'The audit ID returned by startSiteAudit.' Schema coverage is 100%, so the description adds no extra meaning beyond what the schema already provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool polls the status of a running site audit and explicitly lists possible statuses (QUEUED, CRAWLING, etc.). It distinguishes from siblings like getSiteAuditReport by specifying this is for progress polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance: call every 5-10 seconds after startSiteAudit until COMPLETE, then switch to getSiteAuditReport. Also includes a 'Pick the right tool' section comparing with getSiteAuditReport.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

inspectImageSessionA

Read-onlyIdempotent

Retrieve detailed information about an image generation session and all its assets.

Returns:

Session metadata (creation time, name, status)
List of all assets with their prompts, toolchains, and status
Parent-child relationships showing iteration history

Use this to:

Review what was generated in a session
Find asset IDs for iteration
Understand the generation history and toolchains used

ParametersJSON Schema

Name	Required	Description	Default
`sessionId`	Yes	The session UUID to inspect

Output Schema

ParametersJSON Schema

Name	Required	Description
`name`	Yes
`assets`	Yes
`status`	Yes
`sessionId`	Yes
`assetCount`	No

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and destructiveHint=false. The description adds valuable context beyond that by detailing what information is returned (metadata, assets, relationships), which helps the agent understand the tool's output without contradicting annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, uses bullet points for clarity, and front-loads the main purpose. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description covers the essential aspects: returns session metadata, asset lists, and relationships. It is complete for a read-only inspection tool with clear use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with the only parameter sessionId having a format and description. The description does not add additional semantic details about the parameter, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Retrieve detailed information about an image generation session and all its assets,' specifying the verb, resource, and scope. It distinguishes from sibling tools like generateImage and iterateImage.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly lists three use cases: reviewing session content, finding asset IDs for iteration, and understanding history/toolchains. This provides clear guidance on when to use this tool, with no mention of when not to use, but the use cases imply exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

iterateImageA

Refine, modify, or create variations of an existing generated image.

Use this to:

Edit specific parts of an image ("change the background to blue", "add a title")
Apply style changes ("make it more minimalist", "use darker colors")
Fix issues ("remove the text", "make the icon larger")
Crop the image to specific coordinates

For diagram iterations:

Include the original Mermaid/D2/Vega source in your prompt to preserve structure
Be explicit about visual issues (e.g., "the left edge is clipped")

ParametersJSON Schema

Name	Required	Description
`cropX1`	No	Crop: X coordinate of the top-left corner in pixels
`cropX2`	No	Crop: X coordinate of the bottom-right corner in pixels
`cropY1`	No	Crop: Y coordinate of the top-left corner in pixels
`cropY2`	No	Crop: Y coordinate of the bottom-right corner in pixels
`prompt`	Yes	Detailed instruction for the iteration. Be specific about what to change. Examples: 'Change the primary color to #0033A0', 'Add a subtle drop shadow'
`assetId`	Yes	The asset UUID of the image to iterate on
`sessionId`	Yes	The session UUID containing the image to iterate on

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	No
`width`	No
`format`	No
`height`	No
`status`	Yes
`assetId`	Yes
`sessionId`	Yes
`parentAssetId`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate readOnlyHint=false (mutation) and destructiveHint=false. The description adds value by detailing behaviors like editing parts, style changes, cropping, and fixing issues, and advising to include source for diagrams to preserve structure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and numbered steps, front-loading the main purpose. Every sentence adds value, and it is appropriately concise without being terse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, 3 required, output schema present), the description covers editing, cropping, and diagram iterations with guidance on preserving source. It fulfills all informational needs for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, providing descriptions for all 7 parameters. The description enhances this with examples for the prompt parameter (e.g., 'Change the primary color to #0033A0') and clarifies the cropping coordinates as top-left and bottom-right, aiding the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs like 'refine', 'modify', and 'create variations' on an existing image, clearly distinguishing it from sibling tools like generateImage (new image) and exportImageAsset (exporting). The list of use cases further clarifies the scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states 'Use this to:' followed by concrete scenarios, and provides a specific 'For diagram iterations:' section with numbered steps. While it doesn't explicitly state when NOT to use, the purpose is clear and contrasts well with siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

previewPageAuditA

Read-onlyIdempotent

Run an instant quality audit of a single URL. Returns a score (0–100), a score label (Well Optimized / Good / Needs Attention / Poor), a breakdown of Open Graph and social metadata checks, any issues found, and mock social previews for Facebook, Twitter, LinkedIn, and Google.

This is a synchronous, single-URL check — it returns results immediately without creating a persisted audit. It does not count against your audit page quota.

Score labels: Well Optimized (≥90) · Good (≥80) · Room for Improvement (≥70) · Needs Attention (≥60) · Poor (<60)

Pick the right tool: previewPageAudit → Instant check of one URL (no quota consumed, returns immediately) startSiteAudit → Crawl and audit an entire domain (async, uses quota)

ParametersJSON Schema

Name	Required	Description	Default
`url`	Yes	The full URL of the page to audit (e.g. https://example.com/product).

Output Schema

ParametersJSON Schema

Name	Required	Description
`url`	Yes
`score`	Yes	Quality score 0–100
`checks`	No	Individual check results keyed by check name
`issues`	No	Issues found on the page with severity and guidance
`summary`	No
`previews`	No	Social card mock previews: facebook, twitter, linkedin, google
`scoreLabel`	Yes	Human-readable score tier

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds that the check is synchronous, returns immediately, does not persist an audit, and does not count against quota, complementing annotations perfectly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, well-structured: first sentence states core action and output, then clarifies synchronous/non-persisting nature, then lists score labels, then provides tool comparison. No superfluous sentences.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, the description sufficiently explains the return values (score, label, breakdown, issues, mock previews) and score ranges. It covers all necessary context for an agent to use this tool effectively without needing to inspect the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% for the single 'url' parameter, with description 'The full URL of the page to audit (e.g. https://example.com/product).' The tool description repeats the example but adds no new semantic value beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states it runs an instant quality audit of a single URL and lists the returned data (score, label, breakdown, issues, mock previews). It clearly differentiates from sibling tools like startSiteAudit which is async and crawls an entire domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description directly provides a 'Pick the right tool' section comparing previewPageAudit (instant, no quota) with startSiteAudit (async, uses quota), giving explicit guidance on when to use each.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

startSiteAuditA

Start a full site audit for a domain. Audits each page for Open Graph, social media, and SEO metadata quality, then generates an AI-powered overview and per-page scores.

The urls array can be sourced from anywhere — discoverSiteUrls structured output, a codebase route scan (read route files and construct full URLs), a sitemap, or a manually provided list. Calling discoverSiteUrls first is NOT required.

For 'audit all': pass every URL from discoverSiteUrls structured output directly. For 'codebase scan': find routes in the project files (Next.js app/, pages/, React Router config, etc.), prepend the domain, and pass them here. If urls is omitted the backend crawls the domain internally.

Audits are asynchronous and can take several minutes. This tool returns an audit ID immediately — use getSiteAuditStatus to poll progress, then getSiteAuditReport to retrieve the completed report.

Pick the right tool: discoverSiteUrls → Crawl-based page discovery (use when you don't have the codebase) startSiteAudit → Run the audit — accepts URLs from any source getSiteAuditStatus → Poll until COMPLETE getSiteAuditReport → Get the full report previewPageAudit → Instantly audit a single URL without waiting

ParametersJSON Schema

Name	Required	Description
`urls`	No	Specific URLs to audit. Pass the user-selected subset from discoverSiteUrls. When omitted, the audit crawls the domain internally.
`domain`	Yes	The domain to audit. Include the protocol (e.g. https://example.com).
`pagesRequested`	No	Number of pages to audit (1–500). Defaults to the length of the `urls` array if provided, otherwise 10. Your plan's monthly URL quota limits the maximum across all audits.
`siteContextText`	No	Homepage text from discoverSiteUrls structured output (`siteContextText`). Including this enriches the AI-generated overview and top-priority analysis.

Output Schema

ParametersJSON Schema

Name	Required	Description
`domain`	Yes
`status`	Yes	Initial status — always QUEUED on creation
`auditId`	Yes	ID to pass to getSiteAuditStatus and getSiteAuditReport
`pagesRequested`	Yes

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that audits are asynchronous and can take several minutes, returns an audit ID, and instructs to use getSiteAuditStatus for polling. Also explains behavior when `urls` is omitted (backend crawls). No contradiction with annotations (readOnlyHint=false, etc.).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured and front-loaded with core purpose, then parameter guidance, then async behavior and tool selection. It is somewhat lengthy but every sentence adds value. Minor redundancy in repeating 'audit all' explanation could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complexity (asynchronous, multiple URL sources, polling), and full schema coverage plus output schema existence, the description is complete. It covers all aspects needed for correct tool invocation and result handling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds significant context: for `urls`, explains sourcing methods; for `domain`, includes protocol requirement; for `pagesRequested`, explains default and plan limits; for `siteContextText`, explains its role in enriching the overview. This goes well beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('start a full site audit') and what it audits (Open Graph, social media, SEO metadata). It distinguishes from sibling tools by listing alternatives and their purposes, such as discoverSiteUrls for crawl-based discovery and getSiteAuditStatus for polling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on when to use this tool vs. siblings, including a dedicated section 'Pick the right tool'. Explains how the `urls` array can be sourced from discoverSiteUrls, codebase scan, sitemap, or manual list, and that calling discoverSiteUrls first is not required.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation4/5

Most tools have clearly distinct purposes (e.g., discover vs. audit vs. report, generate vs. iterate vs. export). However, getOgData, getLinkPreview, and previewPageAudit all deal with social previews, which could cause minor confusion. Overall, boundaries are well-defined.

Naming Consistency5/5

All tools follow a consistent verb_noun camelCase pattern (e.g., generateImage, getOgData, startSiteAudit). The naming is predictable and descriptive, with no mixing of conventions.

Tool Count5/5

With 16 tools, the server covers both image generation and site auditing without being overwhelming. Each tool serves a distinct and necessary function within its domain.

Completeness5/5

The tool set covers the full lifecycle: site discovery, audit initiation, status polling, report retrieval, single-page preview, and multiple data extraction methods. Image generation includes creation, iteration, export, and session inspection. No obvious gaps.

Maintenance

ActivityStale

ResponsivenessSyncing

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

ReefAPI A
io.github.reefapi
One MCP server for 180+ live web-data APIs returning clean JSON from sites that block scrapers.
Web Scraping Browser Automation
522
UnifAPI
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2
Indices
io.indices
Official Indices MCP server. Turn any website into a reliable API.
Web Scraping Browser Automation
1
microlink A
io.github.pipeworx-io
Microlink MCP — wraps Microlink API (free tier, no auth required)
Web Scraping Search Browser Automation
332

Related MCP Servers

MCP NPX Fetch
Web Scraping Browser Automation RAG Systems
tokenizin-agency
A
license
A
quality
D
maintenance
A powerful MCP server for fetching and transforming web content into various formats (HTML, JSON, Markdown, Plain Text) with ease.
Updated 2 years ago (2024-12-26 09:28 UTC)
4
24,262
41
MIT
@hauntapi/mcp-server
Browser Automation Data Platforms Web Scraping
Darko893
A
license
A
quality
B
maintenance
Web extraction MCP server for AI agents. Extract structured data from any URL with built-in Cloudflare bypass, JavaScript rendering, and intelligent parsing. Returns clean markdown or JSON.
Updated a month ago (2026-07-29 13:22 UTC)
5
794
2
MIT
screenshotfreeapi
Browser Automation Web Scraping
chinkauchenna2021
A
license
A
quality
C
maintenance
MCP server for ScreenshotFreeAPI – capture website screenshots, render HTML/PDF, and fetch app store listing screenshots from any MCP-compatible AI client.
Updated 2 months ago (2026-06-20 12:42 UTC)
7
14
MIT
cloudflare-crawl-mcp
Browser Automation Web Scraping
bidouilles
F
license
A
quality
D
maintenance
MCP server for Cloudflare Browser Rendering Crawl API. Fetches and crawls web pages, returning clean Markdown optimized for LLM consumption.
Updated 6 months ago (2026-03-13 09:11 UTC)
3

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/securecoders/opengraph-io-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

OpenGraph MCP Server (og-mcp)

Global Installation

Quick Install

CLI Installer (Recommended)

Claude Desktop Extension

Authentication

Option 1 — OAuth 2.1 (recommended for hosted deployments)

Option 2 — x-app-id header (legacy / local dev)

Client Configuration

OAuth (no static config needed)

x-app-id fallback

Claude Desktop

Claude Code

Cursor

VS Code

Windsurf

JetBrains AI Assistant

Zed

Available Tools

OpenGraph.io Data Tools

Site Audit & Link Preview Tools

Image Generation Tools

Image Generation

Generate Image

Iterate Image

Inspect Image Session

Export Image Asset

Guided Workflows (Prompts)

How it works

Setup and Running

Configuration

OAuth 2.1 (hosted HTTP server)

x-app-id fallback / local dev

Stdio transport

Transport Options

Stdio Transport (Recommended)

HTTP/SSE Transport

Troubleshooting

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

Option 2 — `x-app-id` header (legacy / local dev)