seodraft

Add topics

add_topics

Adds questions to the topic bank. Uses BYO DataForSEO for Google volume, AI search volume, and intent when connected; otherwise stores estimates. Costs the user about USD 0.11 per batch, whatever the term count; terms already measured in the last 30 days are skipped and cost nothing. One call covers all terms at that cost. Every term is checked against the stored topics and against the others in the same call before anything is measured. duplicates names terms identical to something already there (scope stored collapsed onto an existing topicId; scope in-call was sent twice in this call); no row is created. similar names terms withheld for competing with an existing topic (score, term, topicId, inserted: false); re-sending with allowSimilar: true stores both on purpose (inserted: true then). similarityThreshold is the cutoff in use. published names terms withheld for resembling a page the site already published, with url, path, score, inserted: false and a source: source sitemap is a content page from import_sitemap, compared by a title inferred from its slug (inferredTitle); source profile is a page that sells, such as the home, compared by the keyword the founder declared for it in profile.pageKeywords (targetKeyword). Each published entry names the phrase and the existing URL it resembles; re-sending with allowSimilar: true stores it anyway. semanticOverlaps is a separate, softer signal: terms that were stored and measured, but a classifier read as asking the same question as an existing topic in different wording: probability, term and the topicId it overlaps, stored either way. semanticOverlapThreshold is the cutoff in use, and the list is empty when the classifier is unavailable. Returns measured (terms DataForSEO answered for) and unmeasured (terms it did not); an unmeasured term keeps source estimate and is not ranked. volumeStatus and aiVolumeStatus on the returned topics report observed, unavailable or unmeasured; an unavailable volume is never a 0. Can be refused before spending with degraded: true, reason: spend-limit and a spend object naming the ceiling that tripped; nothing is charged. resurrected names terms whose archived topic was brought back instead of creating a new row, keeping the metrics and brief it was archived with.

Input Schema

TableJSON Schema

Name	Required	Description
`terms`	Yes
`source`	No
`workspaceId`	No	The workspace this call acts on, as listed by list_workspaces. Left out, the call uses the workspace the account is in right now.
`allowSimilar`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 2, 2026

addedInput schema / properties / workspaceId

Added value: +{
+  "description": "The workspace this call acts on, as listed by list_workspaces. Left out, the call uses the workspace the account is in right now.",
+  "type": "string"
+}

First observedSep 27, 2026

TDQS

A4.2/5.0

Behavior5/5

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, destructiveHint=false), it discloses cost (~USD 0.11 per batch), 30-day skip behavior, spend-limit refusal via degraded:true with nothing charged, and per-outcome semantics for duplicates, similar, published, semanticOverlaps, unmeasured and resurrected. This is unusually rich disclosure for a mutating tool.

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

Conciseness5/5

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

For a tool with no output schema, the dense prose is doing necessary work: cost and skip rules are front-loaded, then return-field semantics. Some sentences are telegraphic ('duplicates names terms identical to something already there'), but almost every clause carries actionable information rather than restating structured fields.

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

Completeness4/5

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

With no output schema and 25% schema coverage, the description carries the return-value and behavior burden and mostly does so: it enumerates the result buckets (measured, unmeasured, duplicates, similar, published, semanticOverlaps, resurrected) and status values. Gaps remain around the `source` parameter and the exact shape of the `terms` input.

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

Parameters3/5

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

Schema description coverage is only 25%, so the description must compensate. It explains allowSimilar well (re-sending stores withheld terms, inserted:true), but never clarifies the `terms` payload or the `source` enum (add/generate/chat), leaving half the parameters under-specified. Partial compensation merits a 3.

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

Purpose5/5

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

The opening sentence states a specific verb and resource ('Adds questions to the topic bank'), and the surrounding detail about measurement, cost, and dedup makes clear this is the write path distinct from siblings like plan_topics, propose_topics, suggest_topics, and research_topic. An agent can identify the tool without opening the schema.

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

Usage Guidelines3/5

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

The description thoroughly explains what happens during a call (cost, dedup checks, allowSimilar overrides) but never states when to choose this tool over the adjacent topic tools (propose_topics, suggest_topics, plan_topics). Usage is implied by the topic-bank framing rather than explicitly routed.

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

All seodraft tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?