Skip to main content
Glama

CarlNotes

Edit a topic

edit_topic

Change a CarlNotes topic you may edit: its name, tags, visibility (public, invite, or private), how often it brews (daily, weekdays, or weekly), the time of day as HH:MM and the day a weekly brew runs, how many findings a brew keeps (5, 10, 15, or 20), the prompt every brew scores against, sources to add as option and value pairs, source ids to remove, which list_topics shows, and a team to add the topic to or take it off, which follows the team page's rules. Set isPodcastEnabled to turn the topic's Coffee Break podcast on or off. Name only what changes. Making a topic public, removing a source, or adding a topic that is not public to a team saves nothing at first: the result shows the topic as it would read and a confirmation. Ask the person, and once they agree, call again with the same edit and that confirmation. Every prompt save keeps a version, and no brew starts. Use it when the user asks Carl or CarlNotes to change a topic, with phrases like edit this topic, change the prompt, add a source, change the schedule, or add this topic to my team.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "edit_topic"
  }
}

Input Schema

NameRequiredDescriptionDefault
nameNo
tagsNo
promptNo
team_idNoA team to add the topic to or take it off, by the id list_teams shows.
topic_idNoThe topic's id. Optional on a topic-bound server, which already knows its topic.
frequencyNo
addSourcesNo
is_on_teamNoTrue adds the topic to team_id, which is the default, and false takes it off.
visibilityNo
confirmationNoThe confirmation a previous call returned for this same edit, once the person agreed to it.
scheduledTimeNo
removeSourceIdsNo
isPodcastEnabledNo
maxTopicFindingsNo
scheduledDayOfWeekNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false; the description goes well beyond by disclosing the two-phase commit: making a topic public, removing a source, or adding a non-public topic to a team 'saves nothing at first' and returns a preview plus a confirmation that must be replayed with the same edit. It also states that every prompt save keeps a version and that no brew starts, which tells the agent the side-effect footprint precisely.

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

Conciseness3/5

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

The purpose is front-loaded, but the opening sentence is a 100-word run-on that chains ten unrelated facets with commas and 'and', making it hard to scan. The trailing 'Use it when...' sentence partly restates the purpose already implied, so a bulleted or short-sentence structure would have earned more of its length.

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 15-parameter mutation with no output schema and sparse schema descriptions, the description covers the essentials: what changes, the confirmation gate, versioning, and even what the response looks like ('the result shows the topic as it would read and a confirmation'). Remaining gaps are minor — optional topic_id on a topic-bound server and error/permission behavior are not discussed.

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

Parameters5/5

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

With schema description coverage at only 27% and 15 parameters, the description carries the load well: it enumerates the allowed values for visibility, frequency and findings count (5/10/15/20 — not an enum in the schema), explains addSources as option/value pairs, removeSourceIds, the team_id + is_on_team pairing, HH:MM time and weekly day, and the confirmation replay rule. Only topic_id goes unmentioned in prose, and that one is covered by the schema description itself.

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 description names a specific verb ('Change') and resource ('a CarlNotes topic you may edit'), then enumerates the exact editable facets — name, tags, visibility, frequency, brew time/day, findings count, prompt, sources, list visibility, team membership, podcast toggle. It also names sibling-style helpers ('which list_topics shows', the team page rules) and is unmistakably distinct from create_topic or the read_topic_* family.

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

Usage Guidelines4/5

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

It gives an explicit trigger: 'Use it when the user asks Carl or CarlNotes to change a topic, with phrases like edit this topic, change the prompt, add a source, change the schedule, or add this topic to my team.' That is strong when-to-use guidance, but there is no explicit when-not (e.g., use create_topic for a new topic), so a sibling boundary is left to inference.

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.