Skip to main content
Glama

Dashly

by si.dashly
OverviewDiscussionsAdmin

Update a topic

update_topic
Destructive

Changes a topic. Only the fields you send change; fields, statuses and goal replace the whole previous value. To change the unit and keep history correct, send the new unit with unitFactor, which multiplies every stored value and the goal (litres to millilitres: 1000). Ask the person before changing a unit.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
goalNoNew goal, or null to remove it. Replaces the whole goal.
nameNoNew name. Up to 80 characters.
unitNoNew unit. Pair it with unitFactor to convert what is already stored.
colorNoThe topic's own colour, one of: sky, blue, indigo, violet, fuchsia, pink, orange, teal, emerald, cyan, sand, silver. Leave it out and Dashly gives the next colour no other topic uses. Choose by meaning when one fits (sky for water, orange for food, indigo for sleep) and change it when the person asks.
scaleNoA scale { min, max, labels? } of whole steps, labels optional words for some of them ({ "1": "awful", "5": "great" }). Required for rating topics. On an event topic it lets each entry carry a severity (values.severity), e.g. a headache from 1 to 5.
fieldsNoThe full list of extra fields. Replaces the existing list, so include the ones to keep.
visualNoThe scene the topic plays in its tile's level column everywhere (home, every dashboard, its page, the calendar), from the group its type, goal and polarity point to; get_capabilities lists each group's scenes with what they show. Pick by meaning (a piggy bank for savings, a balloon that pops for screen time); leave it out for the one that fits what it tracks. A scene from another group is refused with the ones that fit.
topicIdYesThe topic to change, from list_topics.
polarityNobuild (the default) for something the person wants more of or just tracks; avoid for something they want less of (headaches, panic attacks, cigarettes, takeaway). With avoid, a day with nothing logged is a good day, each entry counts against it, the streak is days without, and a goal can only be a limit (at_most). Set it whenever the topic is something to avoid; ask if unsure.
statusesNoThe full list of task statuses. Replaces the existing list, so include the ones to keep.
unitLabelNoNew spoken label for the unit.
unitFactorNoMultiplier applied to every stored value and to the goal when the unit changes: litres to millilitres is 1000. Needs a new unit, and cannot be repeated once the unit has changed.
descriptionNoNew description, or null to clear it.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
topicYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.1/5.0
Behavior5/5

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

With destructiveHint=true already declared, the description still adds real value: it discloses exactly what is destructive ("fields, statuses and goal replace the whole previous value"), that the unitFactor conversion rewrites every stored value and the goal, and that a unit change warrants human confirmation. That is the kind of what-gets-destroyed/authorship context annotations cannot express.

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?

Four tight sentences, front-loaded with the core mutation behavior and the replace-instead-of-merge rule, followed by the highest-risk operation (unit conversion). No filler or repetition of the title.

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 tool with nested objects and an existing output schema, the description covers the essential patch semantics and the unit-change hazard. It could say more about the required topicId and general confirmation expectations, but the key risks are disclosed.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds meaning the schema does not: which parameters replace wholesale versus which merge, and the coupled unit+unitFactor contract. It does not spell out individual field constraints, which the schema already handles.

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

Purpose4/5

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

The description opens with a specific verb+resource ("Changes a topic") and immediately clarifies that this is a partial/patch update, which separates it cleanly from create_topic and archive_topic. It stops short of actually naming those siblings, so an agent must infer the boundary rather than being told it.

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?

It gives one concrete when-to-do-X instruction ("ask the person before changing a unit") and explains the patch semantics, but offers no explicit guidance on when to reach for update_topic versus merge_topics, archive_topic, or create_topic. Usage is implied rather than stated.

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

All Dashly toolsInspect
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