The Competiflow MCP Server lets AI clients manage competitor monitoring via Competiflow's API. Here's what you can do:
Workspace Management
List, create, and refresh workspaces (queuing fresh checks for all active monitors)
Get weekly digests summarizing competitive changes and opportunities
Competitor Tracking
Add competitors by homepage URL with async discovery (idempotent on duplicates)
List, read, update (cadence/status), or permanently delete competitors
Poll discovery status until completion; handles concurrent discovery conflicts
Monitor Control
Create manual monitors for specific URLs; list, read, update (URL, type, cadence, status, severity), and delete them
Trigger on-demand checks for a specific monitor or all active monitors in a workspace
Supports monitor types (homepage, blog, docs, changelog, pricing) and cadences (hourly, six-hourly, daily, weekly)
Pause monitors/competitors to preserve history; delete removes everything permanently
Change Feed & Triage
Browse a cursor-paginated feed of detected changes, filterable by date, severity, monitor type, and review status
Get full change details, optionally including capture evidence, extracted markdown, or raw before/after diffs
Triage changes by marking them as unreviewed, acknowledged, or dismissed
AI Integration
Works seamlessly with MCP-compatible clients (e.g., Cursor, Claude Desktop, Windsurf) using a single API key
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Competiflow MCP Server Show me recent changes from my competitors."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for Competiflow. Use competitor monitoring as tools in Cursor, Claude Desktop, Windsurf, and any MCP-compatible client.
Track competitors, run discovery, read the interpreted change feed, triage items, and pull workspace digests without leaving your AI client.
Create an API key in the Competiflow dashboard under API keys, then add the server to your client config. COMPETIFLOW_API_KEY is the only variable you need.
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"competiflow": {
"command": "npx",
"args": ["-y", "@competiflow/mcp-server"],
"env": {
"COMPETIFLOW_API_KEY": "sk_live_your_key_here"
}
}
}
}Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"competiflow": {
"command": "npx",
"args": ["-y", "@competiflow/mcp-server"],
"env": {
"COMPETIFLOW_API_KEY": "sk_live_your_key_here"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"competiflow": {
"command": "npx",
"args": ["-y", "@competiflow/mcp-server"],
"env": {
"COMPETIFLOW_API_KEY": "sk_live_your_key_here"
}
}
}
}Related MCP server: Competitor Tracker & Co.
Tool | API | Description |
|
| List workspaces with review counts |
|
| Create a workspace |
|
| Add a competitor by homepage URL. Async discovery, idempotent on duplicate URL |
|
| List competitors with monitors and |
|
| Read one competitor |
|
| Set cadence or status on all its monitors |
|
| Remove a competitor and all its history |
|
| List monitors with status, cadence, and |
|
| Read one monitor. Pass |
|
| Add a manual monitor on a specific URL |
|
| Update URL, cadence, status, or |
|
| Remove a monitor and all its history |
|
| Queue an on-demand check |
|
| Queue checks for active monitors |
|
| Change feed with |
|
| Full change. Pass |
|
| Set |
|
| Weekly workspace summary |
list_workspaces or create_workspace.
add_competitor with a homepage URL.
get_competitor until discovery_status is completed.
refresh_workspace or check_monitor to pull fresh data.
list_changes with since=7d and min_severity, or get_digest for a summary.
get_change with include when you need evidence.
update_change to acknowledge or dismiss items.
add_competitor starts discovery in the background and returns an acknowledgement, not the finished result. Poll get_competitor until discovery_status is completed.
A workspace runs one discovery at a time. Posting the same homepage URL again returns the existing competitor without starting a second run. If a different competitor is still discovering, the call returns 409 discovery_in_progress with active_competitor_id so you know which one to poll.
includeget_change and get_monitor accept an include array to attach the underlying capture in one call:
Token | Available on | Returns |
|
| Extracted fields from the snapshot |
|
| Page markdown from the snapshot |
|
| Before and after diff for the change |
For a change the capture is the post-change page. For a monitor it is the latest successful check, which is the current baseline.
delete_monitor and delete_competitor are permanent. They remove the monitor or competitor along with its check runs, snapshots, and changes. To stop checks while keeping intel history, call update_monitor or update_competitor with status: paused instead.
Poll discovery, do not assume: after add_competitor, poll get_competitor until discovery_status is completed before reading changes. On 409, poll the active_competitor_id from the error.
Filter the feed: pass since (1d, 7d, 30d, or ISO8601), min_severity, monitor_type (homepage, blog, docs, changelog, pricing), and review_status to list_changes instead of pulling everything. Use meta.counts for inbox totals and next_cursor to page.
Interpretation fields: changes and digest items expose why_it_matters for competitive context. recommended_action was removed from the API.
Fetch evidence on demand: only add include to get_change or get_monitor when you need the underlying capture. It adds payload.
Prefer pause over delete: default to status: paused when a user wants to stop a monitor. Reserve delete_* for permanent removal, since it drops history.
The server translates each tool call into a Competiflow v1 API request and returns structured JSON. Your agent sees interpreted changes, severity, and why it matters instead of raw page scrapes.
AI Agent → MCP Tool Call → Competiflow API → Interpreted Change Feed → Structured Response → AI AgentVariable | Required | Description |
| Yes | Your Competiflow API key ( |
Sign up at competiflow.com and create a key under API keys.
npm install
npm run build
COMPETIFLOW_API_KEY=sk_live_... node dist/index.jsMIT
POST /v1/workspaces/:id/competitors. Add a competitor by homepage URL. Idempotent on duplicate URLs. Returns 409 with active_competitor_id when another discovery is running.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Competitor homepage URL | |
| workspace_id | Yes | Workspace id from list_workspaces or create_workspace | |
| monitor_types | No | Limit discovery to these surface types |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Idempotency is disclosed, and 409 error with active_competitor_id is mentioned when another discovery is running. However, side effects (e.g., triggering a discovery) and authorization needs are not described. With no annotations, full burden is on description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences covering the core action, idempotency, and a key error condition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks success response details and full behavioral context. For a tool with 3 parameters and no output schema, the description provides the minimum but does not explain the full result of adding a competitor.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for all three parameters. The description adds little beyond the schema, only relating 'homepage URL' to the url parameter. It does not clarify when 'monitor_types' should be used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly says 'Add a competitor by homepage URL' and notes idempotency on duplicate URLs. It clearly distinguishes from siblings like 'delete_competitor' and 'list_competitors'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., create_monitor). No mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
POST /v1/monitors/:id/check. Queue an on-demand check for one monitor.
| Name | Required | Description | Default |
|---|---|---|---|
| monitor_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. 'Queue an on-demand check' is vague about whether it returns immediately, is idempotent, or has side effects. The HTTP endpoint is redundant for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, one arguably unnecessary (the endpoint). However, it is brief and front-loads the core action. Could be more concise by removing the endpoint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple trigger tool with one parameter and no output schema, the description is minimally adequate but lacks behavioral details that would help an agent understand the asynchronicity and effect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%. The description does not explain monitor_id beyond the schema, missing context like how to obtain valid IDs or format constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queues an on-demand check for a monitor, distinguishing it from sibling tools like get_monitor (read) or create_monitor (create). The verb 'Queue' and 'on-demand' specify the action and scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_changes or refresh_workspace. The description implies manual triggering but does not clarify prerequisites or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
POST /v1/monitors. Add a manual monitor on a specific URL.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| cadence | No | ||
| monitor_type | Yes | ||
| competitor_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It only states 'Add a manual monitor' without explaining what 'manual' entails, side effects, or any behavioral specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, but it is under-specified rather than concise, omitting essential parameter and behavioral information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without output schema, annotations, or parameter descriptions, the tool is insufficiently documented for an AI agent to use correctly. Only the URL parameter is referenced.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description only mentions 'URL' and does not explain competitor_id, monitor_type, or cadence, leaving three parameters completely undefined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a manual monitor'), the resource ('monitor'), and the target ('specific URL'), distinguishing it from sibling tools like delete_monitor or list_monitors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like check_monitor or update_monitor, and no mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
POST /v1/workspaces. Create a workspace for one product or market.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Workspace name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, yet description offers minimal behavioral detail (just 'create'), missing side effects, auth needs, or response characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences covering endpoint and purpose, no wasted words, front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple tool with 1 param and no output schema; description is adequate but lacks hints about uniqueness or response, slightly incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with description of 'name' as 'Workspace name'; description adds no extra meaning beyond schema, baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and resource (workspace) with context 'for one product or market', distinguishing it from siblings like list_workspaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; no when-not-to or context for usage among siblings like create_monitor.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DELETE /v1/competitors/:id. Permanently removes the competitor, its monitors, snapshots, and changes.
| Name | Required | Description | Default |
|---|---|---|---|
| competitor_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly states the operation is permanent and lists affected entities (monitors, snapshots, changes), which is crucial behavioral context. However, it does not mention potential auth or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that conveys the action, scope, and side effects without wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a simple signature (1 param, no output schema). The description covers the purpose and side effects completely for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description must compensate. The single parameter (competitor_id) is self-explanatory in context, and the description adds no extra meaning beyond what the schema provides. A score of 3 is fair given the trivial parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (DELETE, permanently removes) and the resource (competitor), and lists the cascading deletions (monitors, snapshots, changes). This distinguishes it from sibling tools like delete_monitor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for removing a competitor but provides no explicit guidance on when to use or not use this tool, nor mentions alternatives (e.g., archiving). It relies on the user inferring the irreversible nature.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
DELETE /v1/monitors/:id. Permanently removes the monitor and all its changes and snapshots.
| Name | Required | Description | Default |
|---|---|---|---|
| monitor_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the destructive nature ('permanently removes') and cascading delete of changes/snapshots. However, it lacks details on authorization requirements or rate limits. Since no annotations are provided, the description carries the burden, and it partially meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the core action. However, it is too brief and misses an opportunity to briefly describe the parameter. Still, it is front-loaded and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a single undocumented parameter, the description is insufficient for an agent to fully understand how to invoke the tool correctly. It lacks context on how to obtain the monitor_id and what response to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The parameter 'monitor_id' has no description in the schema (0% coverage) and is not mentioned in the description. The description adds zero explanatory value beyond the schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('permanently removes'), the resource ('monitor'), and the scope of deletion ('all its changes and snapshots'). This differentiates it from sibling tools like update_monitor or get_monitor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool over alternatives like update_monitor or deactivate, nor does it mention prerequisites or irreversible consequences.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/changes/:id. Full change detail. Pass include for capture, capture_markdown, or raw_diff evidence.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Optional evidence payloads for get_change or get_monitor | |
| change_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description implies a read-only operation via the 'GET' method, but does not explicitly state that the tool is non-destructive or disclose any behavioral traits beyond what is inferred. Since no annotations are provided, the description carries the burden of transparency but only partially meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two efficient sentences: first stating the purpose, second providing parameter usage. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with two parameters and no output schema, the description adequately covers purpose and optional parameter behavior. It could mention error scenarios or return format but is largely complete given the tool's simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the include parameter by specifying allowed values and their purpose ('capture, capture_markdown, or raw_diff evidence'), partially compensating for the 50% schema coverage. However, it provides no additional semantic for the required change_id parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the HTTP method and resource ('GET /v1/changes/:id') and that it retrieves 'Full change detail', distinguishing it from sibling tools like list_changes (listing) and update_change (modification).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides guidance on using the include parameter for evidence payloads, but offers no comparison to sibling tools (e.g., get_monitor, list_changes) to help the agent decide when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/competitors/:id. Read one competitor with monitors and discovery fields.
| Name | Required | Description | Default |
|---|---|---|---|
| competitor_id | Yes | Competitor id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It mentions the returned data (monitors and discovery fields) but does not explicitly state that the operation is read-only or side-effect-free. Behavioral traits like authorization requirements or limitations are absent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, front-loading the HTTP method. Every word serves a purpose with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read endpoint with one parameter and no output schema, the description covers what it does and what it returns. However, it lacks behavioral context (e.g., safe operation, error scenarios) that would be expected without annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'competitor_id' is fully described in the schema. The description adds no further detail about parameter syntax, format, or constraints beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the HTTP method, resource, and action: 'GET /v1/competitors/:id. Read one competitor with monitors and discovery fields.' It effectively distinguishes from sibling tools like list_competitors by specifying a single resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., list_competitors, update_competitor). The description does not state prerequisites or scenarios for selecting this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/workspaces/:id/digest. Weekly workspace summary with needs-review items and top opportunities.
| Name | Required | Description | Default |
|---|---|---|---|
| period | No | ||
| workspace_id | Yes | Workspace id from list_workspaces or create_workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description only implies read-only behavior without stating it explicitly. It does not disclose side effects, auth requirements, or rate limits. For a tool with no annotation safety net, more behavioral context is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no filler. Efficient but could be more structured. Not overly concise to the point of missing critical info, but it earns its space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and simple params, the description provides a high-level overview. However, it lacks details on response format, pagination, or what 'needs-review items' specifically means. Adequate but not complete for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (workspace_id described, period only has enum). The description adds output content details but does not explain the period parameter beyond 'weekly' which contradicts the enum support for 1d and 30d. It adds some value but leaves a gap for period meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (GET), resource (workspace digest), and content summary (needs-review items and top opportunities). It distinguishes itself from sibling tools like get_change or list_changes by specifying it's a weekly summary. However, it could be more precise about the data scope beyond 'weekly'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings. For instance, does one use this over list_changes for a quick overview? No alternatives or when-not-to-use mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/monitors/:id. Read one monitor. Pass include for capture or capture_markdown from the latest successful check.
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Optional evidence payloads for get_change or get_monitor | |
| monitor_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It correctly indicates a read operation via 'GET' and mentions data source ('from the latest successful check'), but omits details on error handling (e.g., not found), authentication requirements, or side effects, which are important for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences with no extraneous information. It front-loads the HTTP method and purpose, and every word adds value by specifying the action and the optional include feature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (read one monitor by ID), the description is largely complete. It covers the main behavior and the key parameter feature. However, without an output schema, mentioning the response structure or error conditions would enhance completeness, but the current description is adequate for basic use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the 'include' parameter by specifying that the capture and capture_markdown come from the latest successful check, beyond the schema's description of 'Optional evidence payloads.' However, the 'monitor_id' parameter has no description in either the schema or the tool description, leaving a gap in understanding its usage (e.g., format or source).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the HTTP method, path, and action ('Read one monitor'), clearly identifying the tool's purpose. It also specifies the optional 'include' parameter for capture or capture_markdown from the latest successful check, distinguishing it from list_monitors (which lists multiple monitors) and other siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide guidance on when to use this tool versus alternatives like list_monitors or get_change. It implies it is for reading a single monitor, but lacks explicit context for selection, such as 'Use when you need details of a specific monitor' or 'Not for bulk retrieval.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/changes. Cursor-paginated change feed. Response includes meta.counts and max_unreviewed_severity.
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Cursor from next_cursor | |
| limit | No | 1-100, default 25 | |
| since | No | ISO8601 or 1d, 7d, 30d | |
| min_severity | No | ||
| monitor_type | No | ||
| workspace_id | Yes | Workspace id from list_workspaces or create_workspace | |
| competitor_id | No | ||
| review_status | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses it is a GET operation (read-only) and cursor-paginated, but lacks behavioral details such as rate limits, authentication needs, or data freshness. Without annotations, the description carries more weight but still omits important traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise but omits crucial details. It front-loads the HTTP method and pagination, but could include more information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters and no output schema or annotations, the description is too sparse. It mentions response fields but ignores filtering, sorting, and other behaviors, leaving significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description does not explain any parameters beyond what the schema provides. With only 50% schema description coverage, the tool fails to compensate for four undocumented parameters (min_severity, monitor_type, competitor_id, review_status).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists changes using a cursor-paginated feed, with specific response fields. It distinguishes from sibling list tools by specifying 'changes' as the resource, though it doesn't explicitly contrast with other list tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. Does not mention prerequisites, limits, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/workspaces/:id/competitors. List competitors with discovery_status and nested monitors (includes last_run on each monitor).
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace id from list_workspaces or create_workspace |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior. It lists returned fields (discovery_status, nested monitors with last_run) but omits pagination, sorting, authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence of 17 words, front-loaded with the API path and concise return structure, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one parameter and no annotations, the description is nearly complete, though it misses notes on pagination or ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no extra meaning to the workspace_id parameter beyond what the schema already documents.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (List) and resource (competitors within a workspace), and distinguishes from sibling tools like get_competitor (single) and list_monitors (separate monitors).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing all competitors in a workspace but does not provide explicit guidance on when to use this tool versus alternatives like get_competitor or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/monitors. List monitors in a workspace with health, cadence, and last_run.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace id from list_workspaces or create_workspace | |
| competitor_id | No | Filter to one competitor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It indicates a read-only operation (GET) but fails to disclose error conditions, pagination, rate limits, or what happens with invalid workspace_id. This leaves significant behavioral gaps for a list endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—one sentence with no fluff. It front-loads the endpoint and key information, earning its place with zero wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (2 params, no output schema) but the description only mentions three return fields. Missing details like ordering, pagination, or error handling. Given complexity, it is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
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 add extra meaning beyond the schema's parameter descriptions, but it does list return fields which partially compensates for the missing output schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists monitors in a workspace, mentions the HTTP method GET, and specifies included fields (health, cadence, last_run). This distinguishes it from sibling tools like get_monitor (single) and create_monitor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing monitors in a workspace but does not provide explicit when-to-use, when-not-to-use, or alternatives. Context from sibling tool names suggests this is for bulk retrieval, but no guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GET /v1/workspaces. List workspaces with needs_review_count and monitor totals.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden of transparency. It discloses the HTTP method (GET) implying read-only behavior, and mentions the returned fields. However, it does not address authentication, rate limits, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two short sentences, front-loaded with the endpoint. Every word adds value, and there is no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a zero-parameter tool with no output schema, but it could be more complete by mentioning that it returns all workspaces (no filtering) and possibly noting the default ordering or any limits. It does not explain how it differs from other list tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so the baseline is 3. The description adds value by specifying the output fields (needs_review_count and monitor totals), providing meaningful semantics beyond the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List workspaces' and specifies additional details about the output fields (needs_review_count, monitor totals). It distinguishes itself from sibling tools that operate on different resources (monitors, competitors, changes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implicitly suggests usage for fetching workspace metadata, but lacks guidance on filtering, pagination, or conditions that would warrant using other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
POST /v1/workspaces/:id/refresh. Queue checks for all active monitors, or one competitor when competitor_id is set.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_id | Yes | Workspace id from list_workspaces or create_workspace | |
| competitor_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must carry behavioral context. Only states it queues checks, but does not disclose async nature, side effects, rate limits, or whether it is destructive. Lacks significant behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise single sentence, includes HTTP method (minor redundancy). No wasted words, but could be slightly more structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing output schema and does not explain return values, error states, or lifecycle of the queued checks. Incomplete for a tool that triggers asynchronous operations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: competitor_id is explained as targeting one competitor. workspace_id description in schema is already clear. Schema coverage is 50%, but description compensates by clarifying competitor_id usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action: queues checks for all active monitors, or a specific competitor when competitor_id is set. Distinguishes from sibling tools like check_monitor (single check) and list_monitors (read-only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs siblings. Does not mention prerequisites, alternatives, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PATCH /v1/changes/:id. Set review_status to unreviewed, acknowledged, or dismissed.
| Name | Required | Description | Default |
|---|---|---|---|
| change_id | Yes | ||
| review_status | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description mentions it is a PATCH operation, implying modification, but does not disclose side effects, authorization requirements, rate limits, or idempotency. With no annotations, the description fails to provide sufficient behavioral details beyond the bare action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the HTTP method and endpoint. Every word is necessary; no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and no output schema, the description covers the core action and allowed values. However, it omits error conditions, relationships to other resources, and any context about when updates are valid, leaving gaps for a full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It lists the allowed enum values for review_status, adding meaning beyond the schema. However, it does not explain the semantic difference between unreviewed, acknowledged, and dismissed, nor does it define change_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the HTTP method and resource (PATCH /v1/changes/:id) and the specific action of setting review_status to one of three enumerated values. It distinguishes the tool from siblings by naming the specific resource 'changes.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like list_changes or update_competitor. No prerequisites or context are provided. The description simply states the action without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PATCH /v1/competitors/:id. Set cadence or status on all monitors for this competitor.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | ||
| cadence | No | ||
| competitor_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Given no annotations, the description partially discloses the bulk side effect of setting cadence/status on all monitors. However, it omits idempotency, permission requirements, reversibility, and confirmation of changes. More detail is needed for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. It quickly communicates the HTTP method and core action. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 3 parameters, no output schema, and no annotations, the description only covers the core action. It omits crucial context such as expected output (e.g., success message or updated object), error conditions, idempotency, and prerequisite conditions. Incomplete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning by stating that status and cadence are applied to all monitors, but it does not explain the enum values (e.g., what 'paused' or 'hourly' mean). The description elevates baseline from 2 to 3 by providing context about bulk application.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Set cadence or status on all monitors for this competitor' which clearly indicates the tool's action and resource. It distinguishes from sibling tools like add_competitor (creation) and update_monitor (individual monitor updates), though there is slight ambiguity about whether it updates the competitor itself or just monitors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or when-not-to-use guidance. However, from sibling context (update_monitor exists), it implies this tool is for bulk updates on all monitors of a competitor. The description lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PATCH /v1/monitors/:id. Update url, monitor_type, cadence, status, or min_severity. Use status paused to keep history.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| status | No | ||
| cadence | No | ||
| monitor_id | Yes | ||
| min_severity | No | ||
| monitor_type | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It mentions it's a PATCH (partial update) and hints that pausing preserves history, but does not disclose side effects of updating other fields (e.g., whether changing url triggers a restart, whether data is lost). For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with two sentences. It front-loads the HTTP method and endpoint, then lists updatable fields. Every sentence adds information. However, it could include a brief note on typical use without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters (1 required), no output schema, and no annotations, the description is too brief. It does not explain required parameters (monitor_id), success/error behavior, response format, or prerequisites. The tool is a mutation with moderate complexity, and the description lacks contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning. It enumerates 5 of 6 parameters (excluding monitor_id) but provides no additional context about their formats or allowed values beyond what the enum constraints already specify. The hint about 'status paused' adds some value, but overall the description does not compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it updates specific fields (url, monitor_type, cadence, status, min_severity) on a monitor resource. It uses a PATCH verb and identifies the resource via /v1/monitors/:id. While it does not explicitly distinguish from sibling tools like create_monitor or delete_monitor, the list of fields and the status hint provide enough clarity for a developer to understand its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a specific usage hint: 'Use status paused to keep history.' This gives a when-to-use scenario for pausing. However, it does not mention when not to use this tool, prerequisites (e.g., monitor must exist), or alternatives. The hint is helpful but limited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0add_competitorcheck_monitorcreate_monitorcreate_workspacedelete_competitordelete_monitorget_changeget_competitorget_digestget_monitorlist_changeslist_competitorslist_monitorslist_workspacesrefresh_workspaceupdate_changeupdate_competitorupdate_monitorScored across 18 tools
Each tool targets a distinct resource and action (e.g., competitor vs monitor vs change). There is no overlap; even 'add_competitor' and 'create_monitor' address different entities. An agent can reliably select the correct tool.
All tools follow a consistent verb_noun pattern (e.g., add_competitor, list_changes, update_monitor). Verbs are clear and nouns match resource names without mixing conventions.
18 tools cover the full lifecycle of competitors, monitors, changes, and workspaces. The count feels well-scoped for a monitoring service—not too few to miss functionality nor too many to overwhelm.
The tool surface covers CRUD for competitors, monitors, and changes, plus check/refresh triggers and a digest. However, workspace management is incomplete (no delete or update workspace), creating a minor gap.
Track competitors from your AI assistant: change feed, page snapshots, labels and alerts.
Give an AI agent eyes on the web: turn any feed, page, or stream into deduplicated change events.
AI-triaged brand, competitor and demand mentions from Reddit, Google News and search.
Live market intelligence & AI content strategy: trends, competitor moves, content calendar.
