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., "@jev-marketing score these creative briefs for hook and brand fit"
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.
Seven marketing decisions. One small engine.
An open-source Python toolkit for inspecting ads, scoring briefs, reviewing search terms, detecting fatigue signals, comparing landing-page promises, and assessing business lead fit. Deterministic calculations handle counts and dates. Optional Jev calls handle structured classification and scoring.
Explore the interactive demo · Read the source · MIT license
The browser presentation uses synthetic examples and frozen, deterministic engine output. It does not call a model. There are no benchmark or return-on-investment claims.
Workflow | What it does | What to review |
| Tags supplied ad records by hook, creative format, and offer; calculates observed days running. | Tags describe the imported sample, not the entire ad library. |
| Groups observed 60-day longevity by format with eligible denominators and censored records. | Descriptive sample counts, not survival probabilities or profitability. |
| Scores the hook, brand fit, and readiness of a supplied creative brief. | Scores do not predict ad performance. Low confidence routes to review. |
| Classifies supplied search terms and exports negative keyword candidates. | Review conversions and match types before changing an account. |
| Compares frequency and CTR across two sufficiently sized observation windows. | A fatigue signal is an observation, not causal proof. |
| Scores supplied ad promises against supplied landing-page text. | No crawling, usability audit, factual verification, or conversion prediction. |
| Scores submitted business facts from 0 to 100 against an explicit ideal-customer profile. | Business fit only, with no sensitive demographic criteria. |
Related MCP server: PrePilot MCP Server
Python 3.11 or newer recommended. The runtime uses the Python standard library, with no third-party runtime dependencies.
git clone https://github.com/stas4000/jev-marketing.git
cd jev-marketing
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m jev_marketing demoOn Windows, activate with .venv\Scripts\activate instead. No API key or network call is needed for the demo. The installed jev-marketing command exposes the same interface.
Run one workflow and save its output:
python -m jev_marketing list
python -m jev_marketing run ad_tags \
--input examples/ad_tags.json --mode demo --output ad-tags.jsonReview a CSV search-term export with a separate context file:
python -m jev_marketing run search_terms \
--input examples/search_terms.csv \
--context examples/search_terms_context.json \
--mode demo --output search-review.jsonCSV import is supported for search_terms; other workflows use JSON. The tool produces JSON, including candidates and their evidence, without writing to an ad account.
Each JSON input is an object containing records plus the context required by its workflow. Start from the complete, runnable files in examples/.
Context | Fields |
Observation date |
|
Brand |
|
Ideal customer |
|
Workflow | Record fields |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Dates, numeric values, record IDs, and workflow-specific constraints are validated before analysis. Fatigue windows must have equal duration and must not overlap. Input and output records retain source IDs so results can be traced to the supplied data.
Live calls are opt-in. Store credentials in environment variables, never input files or command-line flags. Set TYPESAFE_API_KEY securely in your environment for the default direct provider, or OPENROUTER_API_KEY for OpenRouter.
# Uses TYPESAFE_API_KEY from your environment.
python -m jev_marketing run briefs \
--input examples/briefs.json --mode live \
--provider typesafe --output live-briefs.json
# Uses OPENROUTER_API_KEY from your environment.
python -m jev_marketing run leads \
--input examples/leads.json --mode live \
--provider openrouter --output live-leads.jsonProvider | Endpoint | Model | Environment variable |
TypeSafe |
|
|
|
OpenRouter |
|
|
|
The five language workflows use typed choice or score questions. survival and fatigue are calculations and do not need a model, including in live mode. The default review threshold is 0.7; override with --confidence-threshold when you have validation evidence for your use case.
Jev scores use an explicit three-level rubric: weak, partial, or strong support. The result maps these levels to a 0–100 presentation. This is a rubric score, not a precise business probability. The deterministic demo uses illustrative confidence 0.5, which routes its model-based examples to review under the default threshold. Demo probabilities are fixtures, not calibrated uncertainty.
Live mode sends supplied context and records to the configured provider. Minimize personal data and use only data you are authorized to process. Provider failures are surfaced without automatic retries; output files are replaced only after a complete successful run. Usage fields reflect provider data where available; unavailable billing and token values remain unknown.
Official references: API contract, choice primitive, score primitive, models. Provider availability and model aliases may change.
Every result includes schema_version, workflow, mode, method, limits, usage, and rows, with a summary where relevant. Each row retains its source ID, decision, confidence where applicable, and supporting evidence. The schema also carries workflow-specific tags, scores, counts, or candidate fields.
The presentation's docs/data.json is generated by the engine, not manually written:
python -m jev_marketing demo --output docs/data.json
python -m http.server 8080 --directory docsOpen http://localhost:8080. The no-build site works from GitHub Pages under a repository subpath. Readers can select all seven examples, inspect input and output, and download the selected JSON. It has no account connection or analytics. The page loads Roboto from Google Fonts, with a local system-font fallback.
On 20 September 2026, a separate live check sent nine synthetic records through four workflows on OpenRouter. The provider reported $0.00021126 for nine calls. Sequential wall time was 4.767 seconds, including CLI startup. The resolved model was typesafe/jev-1.13-20260917.
A buyer query was kept, while job-seeking and educational queries became negative candidates. Matched and mismatched landing examples scored 99 and 0; matching and poor-fit business leads scored 99 and 0. Both creative briefs were retained for review because their confidence was low. These are observed synthetic-case outputs, not evidence of production accuracy, calibrated confidence, or typical latency and cost.
See the sanitized live check results. The interactive browser workbench continues to show deterministic demo results, not this live run.
The same workflows are available through a newline-delimited MCP stdio server:
python -m jev_marketing mcpConfigure an MCP client to launch that command from this checkout or its installed environment. Use the client's tool discovery to inspect the seven workflow schemas. Credentials for live calls must be supplied through the server process environment. MCP tools share the CLI validation and decision engine.
All external provider calls in the test suite are mocked:
python -m unittest discover -s tests -v
python -m jev_marketing demo --output /tmp/jev-marketing-demo.jsonSee CONTRIBUTING.md for fixture regeneration and browser checks.
This is an imported-data toolkit. It does not scrape Meta's ad library, connect to an ad account, apply negatives, upload conversions, or change budgets.
An ad observed running for 60 days may be unprofitable. The longevity summary describes the supplied sample and its observation window; it does not model survival or generalize to all ads.
Keyword heuristics in demo mode are intentionally limited. They exist for reproducibility and interface inspection, not production-quality language understanding.
Live results depend on the model, supplied evidence, rubric, and thresholds. A confident result can still be wrong. Validate on your own held-out examples.
Fatigue thresholds are a transparent heuristic. Inadequate data must remain insufficient; CTR movement does not identify its cause.
Lead scoring uses an explicit business profile and rejects supported sensitive-field inputs. Free text still needs review: do not submit sensitive personal facts or proxy criteria.
A landing-page alignment score is not factual, legal, accessibility, or conversion assurance.
No speed, cost, accuracy, or return-on-investment guarantees are made.
Inspired by this seven-workflow marketing post. This repository is an independent implementation by Stas Sorokin, not an official TypeSafe product. All bundled company, ad, search-term, brief, and lead examples are synthetic. The original post is inspiration, not experimental evidence for this toolkit.
MIT licensed. See LICENSE.
Imported records only, not a complete ad library. Tags are judgments; days observed are not profitability. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full transparency burden and does meaningful work: it warns that tags are judgments, that days observed are not profitability, and that default demo mode uses synthetic heuristics rather than real 'Jev' decisions. This is valuable behavioral disclosure, though it does not describe side effects or return behavior.
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 very concise with no wasted words and front-loads the most important scope constraint. The final 'never Jev' phrase is cryptic but compact; overall the structure is efficient.
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 four parameters, a nested input object, no output schema, and no annotations, but the description does not explain the return shape, the meaning of confidence_threshold, or how this tool differs from siblings. The important caveats are present, but an agent is left without enough information to invoke it confidently in all cases.
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 only 25%, so the description needed to compensate for parameters like confidence_threshold and provider, but it mostly does not. It only adds semantic context for mode by explaining that default demo mode uses synthetic heuristic decisions; the other parameters remain undocumented outside the 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 never states an explicit verb or output object, but the tool name and the phrase 'Tags are judgments' strongly imply it produces ad tag judgments for imported records. It provides scope caveats rather than a clear action statement, so purpose is inferable but vague.
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 gives scope constraints ('Imported records only, not a complete ad library') but does not explain when to use this tool versus siblings or when to switch between demo and live modes. There is no explicit when-to-use or when-not-to-use guidance beyond the import-scope caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rubric scores are judgments, not predictions of ad survival, performance, or conversion lift. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose meaningful behavioral traits: rubric scores are judgments, not predictions of ad survival/performance/conversion lift, and demo mode uses synthetic heuristic decisions rather than Jev. However, it does not explain what operation the tool performs, side effects, or return structure.
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 short and free of filler, but it is not structured around the essential information an agent needs. The opening sentence is a disclaimer rather than a definition of the tool's purpose, so it fails to front-load the most critical content.
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 four parameters, a nested input object, no annotations, and no output schema, this description is grossly incomplete. It leaves the agent unable to understand what 'briefs' means, what to pass as input, or what output to expect, especially given the ad-focused sibling 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?
Schema description coverage is only 25%, so the description must compensate. It clarifies the mode parameter's default behavior and loosely touches on provider via 'never Jev', but confidence_threshold and the actual structure/content of input remain unexplained. The schema's input description also points to nonexistent examples.
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 never states what the tool does; it only provides a caveat about rubric scores being judgments and demo mode being synthetic. There is no verb or resource indicating that this tool generates, retrieves, or evaluates briefs. The core purpose is entirely absent.
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 is given about when to use this tool versus sibling tools such as ad_tags, survival, or fatigue. The only contextual hint is that default demo mode uses synthetic decisions, but this does not help an agent decide between alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Heuristic alert on comparable supplied windows, not causal proof. Audience, placement, spend and seasonality can confound it. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does meaningful work: it labels the output as heuristic and non-causal, names likely confounders, and discloses that default demo mode uses synthetic decisions and never uses Jev. It leaves the return shape and the meaning of 'Jev' unexplained, but the core behavioral traits are unusually well surfaced.
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 only two sentences, front-loaded with purpose, and every clause earns its place. The cryptic mention of 'Jev' slightly reduces clarity, but structurally this is tight and efficiently organized.
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 there is no output schema, no annotations, and only 25% parameter description coverage, the description leaves too much unspecified: what the alert output looks like, how confidence_threshold interacts with the heuristic, what 'Jev' is, and how live mode differs from demo. It reads more like an abstract summary than a callable tool contract.
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 low (25%), so the description must compensate, but it only partially does. It adds context that inputs should be comparable windows and clarifies that demo mode produces synthetic decisions, yet it does not explain provider, confidence_threshold, or how to structure the window comparison beyond the schema's minimal input note.
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 opening clause clearly identifies the tool as a heuristic alert over supplied windows, and the 'not causal proof' qualifier sharpens the nature of its output. However, it does not explicitly state the exact condition being alerted on (e.g., ad fatigue) and does not distinguish itself from sibling 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?
The description implies the tool should be used when the user has comparable windows and wants a heuristic signal, and it warns about confounders like audience, placement, spend, and seasonality. It does not explicitly state when to use this tool instead of siblings, nor does it provide exclusions or alternative tool routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Supplied text only. No page fetching or visual, legal, tracking, accessibility, or conversion audit. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With zero annotations, the description carries the burden and does add real behavioral facts: it operates on supplied text only, and 'Default demo mode uses synthetic heuristic decisions, never Jev' warns that demo output is fabricated rather than coming from the real decision engine. However, it discloses nothing about what live mode does, side effects, or response semantics, so coverage is partial.
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 with zero filler, so it is efficiently compact. But the negative-first structure spends the front-loaded position on what the tool is not, leaving no room for what it does.
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 4-parameter tool with nested input, mode/provider switches, no annotations, and no output schema, a caveat list is not enough. Missing are the core purpose, return-value semantics, live-mode behavior, and any differentiation from six sibling tools, making this inadequate for reliable selection and invocation.
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 only 25% (just the input object), and the description compensates for almost none of the gap. It clarifies that mode=demo yields synthetic decisions, but provider ('typesafe' vs 'openrouter') and confidence_threshold are left semantically empty in both schema and description; input's own description defers to examples that are not shown.
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 is built entirely from negatives — 'Supplied text only. No page fetching or visual, legal, tracking, accessibility, or conversion audit' — and never states a positive verb+resource. The actual operation (matching landing-page text against brand/ICP context) must be inferred from the tool name and the input schema, so the purpose is vague rather than stated.
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 choose landing_match over its siblings (ad_tags, survival, briefs, search_terms, fatigue, leads). The exclusions weakly imply 'bring your own text rather than a URL' and 'don't expect an audit,' but no alternative tool is named and no selection condition is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Business facts versus the supplied ICP only. No enrichment, protected-trait scoring, or automatic rejection. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the transparency burden and does it reasonably well: it explicitly excludes enrichment, protected-trait scoring, automatic rejection, and 'Jev' usage in demo mode. These are meaningful behavioral constraints for an agent deciding whether this tool is safe and appropriate. It does not cover side effects or auth, but the stated negatives are valuable.
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 three short sentences with no filler, and the most important constraints are front-loaded. The unexplained term 'Jev' slightly hurts self-containedness, but overall the text is appropriately sized.
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 a nested required input object, two enums, a confidence threshold, and no output schema, the description omits too much: expected input structure, return format, live-mode behavior, and provider implications. The behavioral exclusions are useful, but an agent still needs examples or additional documentation to invoke this 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 description adds useful context for the mode parameter by saying demo mode uses 'synthetic heuristic decisions, never Jev,' and it ties the input to a 'supplied ICP.' It does not elaborate on provider or confidence_threshold, though those are partially self-explanatory from their names, enums, and defaults. With schema description coverage at only 25%, this is partial but real compensation.
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 phrase 'Business facts versus the supplied ICP only' suggests comparison or scoring against an ideal customer profile, and the negative constraints clarify scope. However, there is no explicit verb like 'score' or 'match,' and what the tool actually returns or decides is only implied by 'synthetic heuristic decisions.' It is more than a tautology but remains vague.
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 is given for when to prefer this tool over siblings such as ad_tags, survival, briefs, or search_terms. The description mentions demo mode by default but does not explain when live mode or alternative providers should be used. It is not misleading, but it provides no routing help.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Negative keyword candidates require human review. No keyword match types inferred and no ad accounts changed. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states that no keyword match types are inferred, no ad accounts are changed, and the default demo mode uses synthetic heuristic decisions, which is meaningful safety-relevant context. However, it does not explain what 'never Jev' means or describe the output format and any live-mode 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 is short and front-loaded, but it sacrifices clarity for brevity. The phrase 'never Jev' is cryptic and unexplained, and the three sentences are mostly negations and caveats rather than a coherent explanation of the tool's behavior.
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 nested input object, no output schema, no annotations, and an unusual demo/live mode split, so the description needs to provide much more context. It does not explain what the tool returns, what a synthetic heuristic decision is, how input should be shaped, or how live mode behaves, leaving an agent under-equipped to invoke the tool 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?
Schema description coverage is only 25%, and the description does little to compensate. It references 'demo mode' and hints at synthetic vs. real behavior, but it does not explain the input object structure, provider differences, or confidence_threshold semantics beyond what the schema already contains.
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 never states a clear verb or object: it says 'Negative keyword candidates require human review' and lists what the tool does not do, but does not explicitly say that the tool generates or evaluates negative keyword candidates from search terms. This under-specification forces an agent to infer the tool's core function from its name and constraints.
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 implied workflow context—candidates need human review and no ad accounts are changed—but it gives no explicit guidance on when to choose this tool over siblings like ad_tags, survival, or leads. There are no alternatives named and no conditions for using live versus demo mode.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Descriptive 60-day longevity in this supplied cohort only. Selection/survivor bias can dominate. Not calibrated survival odds or profitability. Default demo mode uses synthetic heuristic decisions, never Jev.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | demo | |
| input | Yes | Workflow data: as_of, records and applicable brand/icp context; see examples. | |
| provider | No | typesafe | |
| confidence_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It does this well by revealing that demo mode uses synthetic heuristic decisions, never Jev, and that outputs are not calibrated survival odds or profitability. It doesn't explain live-mode behavior, but the risk caveats are substantial and non-obvious.
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?
Three tight sentences: the first defines what the tool does, the second states the critical analytical caveats, and the third explains the demo default. Every sentence earns its place, and the most important limitation is 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?
The tool has four parameters, a nested input object, no annotations, and no output schema, so the description must enable correct invocation on its own. It omits what provider affects, how confidence_threshold changes results, and what the tool returns, making the description insufficient for operational 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?
Schema description coverage is only 25%, so the description must compensate, but it only clarifies mode by stating that demo is the default and uses synthetic decisions. Provider and confidence_threshold are left completely unexplained, and the input description relies on 'see examples' rather than concrete field guidance.
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 that the tool reports descriptive 60-day longevity for the supplied cohort, which identifies a specific resource and time horizon. It lacks an explicit imperative verb and doesn't name a sibling, but the caveats about not being calibrated survival odds or profitability make the intended scope clear.
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?
It gives clear usage context: results are cohort-specific and descriptive, and selection/survivor bias can dominate, warning agents not to overgeneralize. It doesn't explicitly name alternative tools or say 'use this when...', but it does convey limitations relevant to choosing this tool.
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.0ad_tagsbriefsfatiguelanding_matchleadssearch_termssurvivalScored across 7 tools
Each tool targets a clearly distinct marketing analytics domain: ad tags, cohort survival, creative briefs, search terms, fatigue, landing page match, and lead qualification. No two tools overlap in purpose or output, and the descriptions reinforce their unique boundaries.
All tool names are lowercase nouns, with underscores used only for multi-word names (ad_tags, search_terms, landing_match). They are consistent in style, though they do not follow a verb_noun action pattern, making the naming slightly less predictable for an agent.
Seven tools is well within the ideal 3-15 range and directly matches the apparent scope of a marketing assessment suite. Each tool earns its place and covers a different facet without bloat.
The set covers the main aspects one would expect from a marketing audit/analysis server: ad tagging, longevity, creative quality, search term negatives, fatigue, landing page alignment, and lead fit. Minor gaps exist, such as no tool for budgeting, audience analysis, or reporting/export, but these do not severely hinder the core diagnostic purpose.
Creative-intelligence MCP for campaign strategy, ad builds, QA, and reporting.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Marketing-measurement MCP: dashboards, cross-channel queries, integrations, and knowledge files.
Marketing MCP: content, SEO, outbound, LinkedIn, ads. Agents provision a sandbox with one POST.
