Skip to main content
Glama

CarlNotes

Create a topic

create_topic

Preview a CarlNotes Topic Draft for the connected account from a name, prompt, sources as option and value pairs, invite emails, visibility, team, tags, brew frequency, and finding limit. Set isPodcastEnabled to turn the topic's Coffee Break podcast on or off. Call only when the user chooses to start a Topic. The first call creates nothing and returns the draft and a confirmation. Show the draft and wait for the user to confirm, then repeat the same fields with that confirmation. Creation uses the existing Topic Draft limits and starts its first brew. A public or invite topic goes on the user's default team, the led team they joined first, unless team names another or is null for no team. For a new send destination, set visibility private, team null, inviteEmails empty, and default Coffee Break on when the view's account budget permits it. Other unsaid fields use the editor's defaults: shared by invite, weekly on Wednesday, ten findings. Use it when the user asks Carl or CarlNotes for a new topic, with phrases like create a topic, start a topic, or have Carl track this.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>",
      "prompt": "<prompt>"
    },
    "name": "create_topic"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameYes
tagsNo
teamNo
promptYes
sourcesNo
frequencyNoweekly
visibilityNoinvite
confirmationNo
inviteEmailsNo
scheduledTimeNo09:00
isPodcastEnabledNo
maxTopicFindingsNo
scheduledDayOfWeekNowednesday

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only tell the agent this is a non-read-only, non-idempotent, non-destructive write. The description adds substantial behavior: first call creates nothing, creation consumes existing Topic Draft limits, the first brew is started, team routing follows the user's default/led team, and defaults are applied to unstated fields. That is exactly the kind of side-effect disclosure the annotations cannot carry.

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

Conciseness4/5

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

Front-loaded with the preview-then-confirm mechanic, the highest-value information, and every sentence carries semantics rather than filler. The opening sentence is a ~50-word parameter enumeration that is hard to parse in one pass, which keeps it from a 5.

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

Completeness4/5

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

For a 13-parameter mutation with no output schema and no per-field schema descriptions, the definition covers the confirmation flow, defaults, team-routing rules, and podcast toggle, which is nearly everything an agent needs to call it correctly. The omission of scheduledTime and the full enum value lists are the remaining holes, both of which the agent would otherwise have to guess.

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

Parameters4/5

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

With 0% schema description coverage across 13 parameters, the description carries the whole burden and mostly meets it: it names name, prompt, sources ('as option and value pairs,' hinting at the sourceOption/value shape), inviteEmails, visibility, team, tags, frequency, maxTopicFindings, isPodcastEnabled, and confirmation, and states defaults (invite, weekly Wednesday, ten findings). Gaps remain: scheduledTime (default 09:00) is never mentioned, and the enum value sets for visibility/frequency/day are only partially surfaced.

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?

States a specific verb and resource (create a CarlNotes Topic) and immediately clarifies that this is a two-phase tool: 'The first call creates nothing and returns the draft and a confirmation.' An agent can distinguish this from edit_topic or follow_topic purely from the text, including the fact that the first invocation is a preview.

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

Usage Guidelines5/5

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

Gives explicit invocation condition ('Call only when the user chooses to start a Topic') plus concrete trigger phrases ('create a topic, start a topic, or have Carl track this'). It also prescribes the exact follow-up flow ('Show the draft and wait for the user to confirm, then repeat the same fields with that confirmation') and a specific recipe for a new send destination.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.