add_article_suggestionAdd a bare article suggestion to a content plan (title + optional intent and reasoning). For richer input that produces a brief-ready suggestion, use create_article_suggestion_with_input.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| intent | No | ||
| projectId | Yes | ||
| reasoning | No | ||
| contentPlanId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate the tool is mutating (readOnlyHint=false) and non-destructive (destructiveHint=false), so the description adds scoping context by calling it 'bare' and noting it only takes title plus optional intent and reasoning. However, it does not disclose details like whether existing suggestions are duplicated, what validation happens, or any expected side effects beyond adding a suggestion. This adds some value over the annotations but leaves room for more.
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 exactly two sentences, with zero filler or redundancy. The core behavior is front-loaded, followed by the alternative routing. Every sentence earns its place.
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 a moderately complex mutation with five parameters, no output schema, and only about half the parameters explained in the description. The description clearly covers the difference from its main sibling, but does not explain the two required ID parameters or what the response looks like. For a tool that creates a record, an agent would benefit from even a basic statement of return behavior, which is missing.
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?
Input schema has no descriptions for any parameter, so the description must compensate. It names title, intent, and reasoning, which helps, but it omits the two required identifiers: contentPlanId and projectId. Their purpose is partially inferable from the phrase 'to a content plan' and their names, but there is no explicit guidance about why projectId is needed or how these relate. Three of five parameters are mentioned, leaving an incomplete and partially confusing picture for the agent.
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 specific: 'Add a bare article suggestion to a content plan (title + optional intent and reasoning).' It names the exact verb, resource, and scope, and explicitly contrasts itself with create_article_suggestion_with_input, making the distinction from a key sibling clear. An agent can tell exactly where this tool fits.
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 explicitly says 'For richer input that produces a brief-ready suggestion, use create_article_suggestion_with_input.' This names the alternative and defines the condition for selecting it. The 'bare' framing also implies when this tool is appropriate, giving an agent an effective decision rule.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Most tools have distinct purposes, but a few pairs could confuse an agent: add_article_suggestion vs create_article_suggestion_with_input, and get_article_brief vs download_brief_markdown vs get_write_handoff all deal with brief content. The detailed descriptions help disambiguate, but the overlap is real.
All tool names follow a consistent verb_noun pattern in lowercase snake_case (create_project, list_opportunities, generate_article_brief, lint_draft). There is no mixing of camelCase, acronyms, or vague verbs, making the naming predictable and readable.
50 tools is excessive for an MCP server, even for a broad platform like content operations. While the scope is large, this many tools will overwhelm agents and increase latency and context cost. Most practical servers are well under 25.
The tool surface covers the full content lifecycle: project creation, research, opportunity clustering, content planning, briefs, drafting, linting, publishing, and reporting. Minor gaps exist (e.g., no delete_project, no remove_destination, no direct analytics beyond distributions), but they are workarounds or handled in the web UI.