Dashly

Update a topic

update_topic

DestructiveIdempotent

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

Name	Required	Description
`goal`	No	New goal, or null to remove it. Replaces the whole goal.
`name`	No	New name. Up to 80 characters.
`unit`	No	New unit. Pair it with unitFactor to convert what is already stored.
`color`	No	The 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.
`scale`	No	A 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.
`fields`	No	The full list of extra fields. Replaces the existing list, so include the ones to keep.
`visual`	No	What the topic draws in its tile's level column everywhere (home, every dashboard, its page, the calendar), from the group its type, goal and polarity point to: a scene, a chart, or plain (no column, the number and its words across the whole tile). get_capabilities lists each group's visuals with what they show. Pick by meaning (a piggy bank for savings, a ring for a daily target, day bars for counting with no goal); use a chart or plain when the person wants a quieter, professional look; leave it out for the one that fits what it tracks. A visual from another group is refused with the ones that fit.
`topicId`	Yes	The topic to change, from list_topics.
`polarity`	No	build (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.
`statuses`	No	The full list of task statuses. Replaces the existing list, so include the ones to keep.
`unitLabel`	No	New spoken label for the unit.
`unitFactor`	No	Multiplier 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.
`description`	No	New description, or null to clear it.

Output Schema

Name	Required	Description	Default
`topic`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 20, 2026

changedInput schema / properties / visual / description

Previous value: -"The 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."New value: +"What the topic draws in its tile's level column everywhere (home, every dashboard, its page, the calendar), from the group its type, goal and polarity point to: a scene, a chart, or plain (no column, the number and its words across the whole tile). get_capabilities lists each group's visuals with what they show. Pick by meaning (a piggy bank for savings, a ring for a daily target, day bars for counting with no goal); use a chart or plain when the person wants a quieter, professional look; leave it out for the one that fits what it tracks. A visual from another group is refused with the ones that fit."

changedInput schema / properties / visual / enum

Previous value: -[
-  "climb",
-  "building",
-  "rocket",
-  "piggy",
-  "glass",
-  "cups",
-  "balloon",
-  "hourglass",
-  "boat",
-  "cairn",
-  "skyline",
-  "hotair",
-  "path",
-  "weather",
-  "gumball",
-  "tray",
-  "sun"
-]New value: +[
+  "climb",
+  "building",
+  "rocket",
+  "piggy",
+  "gauge",
+  "ring",
+  "dots",
+  "macros",
+  "plain",
+  "glass",
+  "cups",
+  "balloon",
+  "hourglass",
+  "boat",
+  "cairn",
+  "grid",
+  "skyline",
+  "hotair",
+  "path",
+  "line",
+  "ranges",
+  "weather",
+  "dial",
+  "usual",
+  "days",
+  "gumball",
+  "tray",
+  "sun"
+]

First observedOct 18, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already flag destructiveHint and idempotentHint, yet the description goes well beyond them by disclosing exactly what is destroyed (fields, statuses and goal are wholly replaced by what is sent) and that unit changes rewrite every stored value and the goal via a multiplier. It also adds a consent guardrail for that history-rewriting action, which is the highest-risk behavior of this 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?

Four tight sentences, roughly fifty words, with the core partial-update rule front-loaded and the narrower unit-conversion caveat last. No sentence is filler, and no important clause is buried.

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 tool with an output schema and 100% schema coverage, the description supplies the pieces structured data cannot: merge-vs-replace semantics, the history-rewriting effect of a unit change, and a consent requirement. It omits any pointer to create_topic/merge_topics for adjacent intents, which is the only meaningful gap.

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 100%, so the schema already documents every parameter, including unitFactor's multiplier example and its dependence on a new unit. The description restates the unit/unitFactor pairing but adds no syntax or format detail the schema does not already carry, so baseline 3 applies.

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?

"Changes a topic" gives a clear verb+resource and the following sentences sharpen it into a partial-update tool whose list-valued fields are full replacements. It does not explicitly distinguish itself from siblings like create_topic, merge_topics or archive_topic, but the mutation semantics make the scope unambiguous once read.

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?

The description clearly sets the operating context: send only what should change, and pair a new unit with unitFactor to keep history consistent. It adds a real usage constraint ("Ask the person before changing a unit"), but never names an alternative sibling or states when a different tool should be used instead.

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

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