Dashly

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the bar is lower, yet the description still adds real value: the side effect that every paired screen stops showing the dashboard, the hard restriction on Home, and the requirement to confirm with the person first. It does not state permission requirements or reversibility, but the disclosed blast radius goes well beyond the annotations.

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?

Three short sentences, zero filler, with the core action and its effect front-loaded ahead of the constraint and the confirmation cue. Every clause carries information.

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?

An output schema exists, so return values need no explanation, and the description covers the mutation's side effects, the key constraint, and the required confirmation. Given one simple parameter and full annotation coverage, nothing an agent needs in order to call this correctly 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?

With one parameter at 100% schema description coverage, the schema (including the "from list_dashboards" provenance note) fully documents dashboardId; the description adds no format or sourcing detail. Baseline 3 applies since the schema does the heavy lifting.

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?

States a specific verb and resource ("Archives a custom dashboard") and clarifies the semantics of archiving as hiding rather than a hard delete. It does not explicitly differentiate itself from nearby siblings such as update_dashboard or archive_topic, but the verb+resource pairing is unambiguous and an agent can identify the operation immediately.

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?

Provides concrete usage conditions: "Home cannot be archived" is an explicit when-not rule and "Ask the person first" is a confirmation precondition. It stops short of naming alternative tools for the cases it excludes, but the guidance is clear and actionable rather than implied.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds real value beyond that by spelling out the blast radius (lists and dashboards) and imposing a human-confirmation step, which the 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.

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

Two short sentences, effect first and the confirmation requirement second, with no filler. Every clause 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?

An output schema exists, so return values need no explanation, and the single parameter is fully documented in the schema. For a one-parameter destructive tool, effect plus consent requirement is everything an agent needs to call it correctly.

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?

Schema description coverage is 100% and there is a single required topicId whose schema description already says where to get it ('from list_topics'). The description adds nothing about the parameter, so the baseline 3 applies.

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?

States a specific verb and resource ('Removes a topic') and goes further by naming the observable effects: gone from the person's lists and cards off dashboards. That distinguishes it from a plain delete, though it never explicitly contrasts with siblings like merge_topics or delete_entry.

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?

'Ask the person first' is a genuine precondition and an unusual one worth stating, but it is consent guidance rather than when-to-use guidance. There is no indication of when archiving beats merging or updating a topic, or whether the action is reversible.

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

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

Annotations already declare the non-destructive write profile (readOnlyHint=false, destructiveHint=false), and the description adds real behavior beyond that: availability gated on Dashly Plus with a hard cap of 3, and named failure modes PLAN_REQUIRED / DASHBOARD_LIMIT_REACHED. It also notes errors echo the offending path and allowed values. It stops short of other operational details (e.g. name collisions, ownership).

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?

Purpose is front-loaded and nearly every sentence carries actionable content, but it is a single dense paragraph with semicolon-heavy run-ons mixing document model, parameter semantics, and plan limits into one block. For a schema this complex some length is justified, though light structural separation would help.

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?

An output schema exists, so return values need not be explained, and the description covers what remains: creation semantics, empty-start behavior, document structure, quota/plan failure modes, error reporting, and routing to siblings. Nothing an agent needs to invoke this correctly appears to be 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?

Schema coverage is nominally 100%, so the baseline is 3, but the description adds genuine semantics the schema does not: 'auto' size is derived from the widgets, density 'compact' packs tiles closer, and style overrides card color/icon with icon names drawn from tiles.icons. The widget-compatibility pointer to get_capabilities compensates for the many undescribed nested properties.

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?

Opens with a specific verb+resource ('Creates a dashboard besides home') and immediately scopes it against siblings: update_dashboard for adding cards later, get_capabilities for widget/size rules. An agent can tell this apart from create_topic, update_dashboard, and archive_dashboard without opening any schema.

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?

Explicit when-to-use and when-to-go-elsewhere: empty start if no document, 'Add cards afterwards with update_dashboard', 'Which widgets each type allows... are in get_capabilities', and even design guidance ('Make one dashboard per theme... rather than one long wall'). Alternatives are named with the condition that selects them.

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

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

Annotations (readOnlyHint=false, destructiveHint=false, openWorldHint=false) already establish that this is a non-destructive local write, and the description is consistent with that. It adds genuinely useful side-effect context beyond the annotations: a new topic's tile appears on home automatically and elsewhere only after a card is added, which an agent would otherwise not know.

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 four front-loaded sentences: purpose, placement side effect, reuse workflow, then type/unit rules. Nothing is padded, though the type enumeration duplicates the schema enum and could have been left to the structured field.

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?

For a 12-parameter nested tool with an output schema, the description supplies the purpose, the reuse-first workflow, the placement behavior, and the unit discipline, while the schema handles all validation details. It is complete enough to call correctly, with the only gap being an explicit pointer to update_topic/archive_topic for existing topics.

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?

Schema description coverage is 100% and every one of the 12 parameters carries a rich inline description, so the schema does the heavy lifting. The description's type list largely restates the type enum, and its only extra guidance ('Pick one unit and keep every value in it') is a durable logging rule rather than call-time parameter meaning, so baseline 3 applies.

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 gives a concrete verb ('Creates') and elaborates the resource into a full taxonomy of trackable types, so an agent knows exactly what is being instantiated. It partially differentiates from siblings by naming list_topics and update_dashboard, but never states plainly that the output is a 'topic', leaving the object identity implicit rather than explicit.

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?

'List topics first and reuse a matching one' is explicit, actionable pre-call guidance, and the dashboard-placement sentence clarifies when a separate update_dashboard step is required. There is no when-not guidance (e.g. use update_topic to modify an existing topic instead), so it stops short of full routing coverage.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the danger profile is covered structurally. The description adds a human-in-the-loop requirement ("Ask the person first") that is not derivable from annotations, but it says nothing about permanence, undo, or error behavior on a destructive operation.

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?

Two short, front-loaded sentences with zero padding — the action comes first, the guardrail second. The second sentence is colloquial and its referent ("the person") is vague, which slightly blunts the structure.

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?

For a destructive tool, the description leaves key agent-facing questions unanswered: whether deletion is reversible, whether any archive/restore sibling exists for entries, and what happens if the entryId is unknown. The output schema covers return values and annotations cover the safety flag, but the permanence question is material and unaddressed.

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?

Schema coverage is 100% with a single required uuid parameter, so the schema fully documents entryId including its format. The description adds only the implicit singular scope ("one entry"), which the schema already conveys; baseline 3 is appropriate.

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?

States a specific verb+resource ("Removes one entry") with clear scope (a single entry), so an agent immediately knows what it does. It does not differentiate from siblings, however — notably the archive_* tools that appear to offer a softer removal path for other resources.

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?

"Ask the person first" is a caution about confirmation, not guidance on when to select this tool versus alternatives. No conditions, prerequisites, or alternatives (e.g. archive_topic/archive_dashboard style soft-delete) are named.

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

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

Annotations already declare readOnlyHint=true, non-destructive, and closed-world, covering the safety profile. The description's contribution beyond that is the scope of sensitive data exposed (billing state, fair-use usage, token count), but it says nothing about auth requirements, rate limits, or freshness of the data, and an output schema already documents the return shape.

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?

A single tight sentence with no filler and the most salient fields front-loaded. It reads as an unpunctuated fragment rather than a proper sentence, which slightly weakens the structure but wastes no words.

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?

For a zero-parameter read tool with an output schema and full annotation coverage, nothing essential is missing; the description need not restate return values. It could be firmer about whose account is returned, since 'the person's' leaves the subject implicit.

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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies an implicit subject ('the person's') and adds nothing that could conflict with the empty schema.

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 enumerates the specific data the tool surfaces (email, timezone, subscription/billing state, fair-use usage, token count), which makes the resource unambiguous against siblings like get_capabilities or list_dashboards. However, it is a noun-phrase field dump with no verb, so it never explicitly says 'retrieves the current user's account' nor distinguishes itself from update_account.

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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as update_account or get_capabilities. The agent must infer the calling context purely from the enumerated content.

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

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

Annotations already cover read-only, non-destructive, closed-world safety. The description adds meaningful invariants beyond that: the content is the same for everyone, does not change during a conversation, and should be read once and reused.

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?

It is front-loaded with the capability content, then gives the static/read-once usage rule, then notes the equivalent resource. Three tight sentences with no wasted text.

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?

An output schema exists, so return shape need not be explained, and annotations already carry the safety profile. With zero parameters and a clear static-reference usage rule, the description is complete for correct invocation.

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?

The tool takes zero parameters, so the baseline is 4 and there is no parameter meaning to clarify. The description correctly does not add irrelevant input details.

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 states exactly what the tool returns: topic types, allowed widget kinds, card sizes, ranges, plans, and theme options. It distinguishes the tool from sibling dashboard/topic mutation tools by making clear this is a static capability reference, not an action on a dashboard.

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 to read it once before the first dashboard change and reuse it, telling the agent both when to call and not to poll. It also identifies the dashly://capabilities resource as an equivalent alternative.

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

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

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds genuine value beyond that: it explains the returned document structure (a wall of ordered cards, each with 1-4 widgets) and cross-references external dependencies like update_topic for scene and tiles.icons for style.

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?

Return behavior is front-loaded in the first sentence and every subsequent clause conveys domain facts (sizes, style, scene, density, cross-references) rather than filler. It is dense and slightly run-on, but nothing is wasted.

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?

For a single-parameter read tool with an output schema, annotations, and a schema that fully documents the input, the agent has what it needs. The description enriches understanding of the document model and defers widget specifics to get_capabilities, leaving little 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?

Schema description coverage is 100% for the single dashboardId parameter, whose description already says 'from list_dashboards.' The description adds no syntax or format detail about the parameter, so the baseline 3 is appropriate when the schema does the heavy lifting.

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 first sentence states a specific verb and resource: 'Returns one dashboard and its full document.' The singular 'one dashboard' implies distinction from list_dashboards, though it never names the sibling explicitly. The rest of the description is domain model rather than purpose, but the core action is unambiguous.

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?

'Read it before changing it' gives an implicit read-before-mutate directive and points to get_capabilities (tiles.draws) for widget detail. However, it never says when to prefer this tool over list_dashboards or update_dashboard, so the routing 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.

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: result ordering (home first) and the non-obvious fact that the returned url is the person's own link that only opens after they sign in.

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?

Two tight sentences, front-loaded with what is returned, then the calling condition. No filler or restated boilerplate.

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?

An output schema exists, so return values need not be spelled out, and annotations carry the safety profile. What remains — ordering, the sign-in caveat on the url, and when to call — is all present.

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?

The tool takes no parameters, so there is nothing for the description to clarify and the baseline is 4. No source/scope/limit parameters exist that would need explanation.

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?

States a specific verb and resource ('Lists the person's dashboards') and even characterizes the result shape — ordering (home first) and field set (id, kind, title, url). This clearly distinguishes it from get_dashboard (single) and list_topics (different resource).

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?

Gives an explicit trigger: 'Call this when the person asks to see a dashboard and give them its url.' It does not name when NOT to use it or point to get_dashboard for a specific dashboard, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond annotations: this is a full unfiltered enumeration intended as an upfront discovery/caching call, and the ids it returns are reused by other tools. It does not mention whether the list is bounded or truncated.

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?

Three tight sentences, front-loaded with what it returns before moving to usage imperatives. Every sentence earns its place by adding routing or workflow information not present in structured fields.

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?

For a zero-parameter, read-only enumeration tool with an output schema and full annotation coverage, nothing an agent needs is missing. Workflow placement (call first), id reuse, and the unit-conversion constraint are all stated.

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?

The tool takes no parameters, so there is no parameter semantics to document - baseline 4 applies. The field list in the description describes the return payload rather than inputs, and an output schema already exists.

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?

States a specific verb and resource (lists every topic the person tracks) and enumerates the returned fields (id, type, unit, goal, entry count, last entry time). An agent can distinguish it from siblings like list_dashboards or get_dashboard without opening the schema.

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?

Explicitly prescribes when to call it (once at the start), what to do with the result (remember the ids), and the alternative to avoid (creating a near-duplicate topic instead of reusing an existing one - routing to create_topic/update_topic). It also flags the downstream workflow constraint to convert values into the topic's unit before logging, pointing at log_entry.

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

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

Annotations already cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=false), so the bar is lower, yet the description adds real value the annotations cannot: atomic all-or-nothing semantics and that the error identifies the offending entry. It does not mention any permission/auth requirement or rate limiting, so it stops short of 5.

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?

Three tight sentences, front-loaded with the capability and the cap, then the atomicity guarantee, then the routing advice. No filler or repetition of schema detail.

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?

A single-parameter batch write tool with an output schema, so return format need not be described. The description covers capability, limit, failure semantics, and sibling routing — everything needed to call it correctly.

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?

Schema description coverage is 100%, so the nested entry fields (note, tags, value, values, topicId, occurredAt) are fully documented in the schema. The description only restates the 1–50 bound already expressed by minItems/maxItems, adding no new parameter meaning. Baseline 3 applies.

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?

States a specific verb and resource ('Records up to 50 entries in one call') plus concrete scope examples (a meal's foods, a backlog). The batch framing directly distinguishes it from the sibling log_entry, so an agent can route without opening either schema.

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?

Explicitly names the alternative and the condition that selects it: 'Prefer this over repeated log_entry calls.' The meal/backlog examples further clarify the intended multi-entry scenario, leaving nothing to inference.

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

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

Annotations already declare this is a non-destructive, non-open-world write, so the safety profile is covered. The description adds real behavioral context beyond that: the entry is created in the topic's unit (implying unit mismatch is a failure mode) and the call returns today's running total, which sets response expectations.

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?

Four short sentences with the core action front-loaded before the prerequisites, and each directive earns its place. Slight redundancy in "reports today's total" against the existing output schema keeps it from a 5.

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?

For a one-required-parameter write with a complete schema, an output schema, and annotations covering safety, the description supplies the remaining decision-relevant facts: the prerequisite lookup, the unit-conversion constraint, and the backdating field. Nothing an agent needs to invoke it correctly 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?

Schema description coverage is 100% and the schema already documents value/unit conversion, occurredAt timezone handling, and topicId sourcing, so the description is largely restating structured data. Its only marginal addition is tying value conversion to the topic resource, which does not exceed the schema's own example.

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?

Uses a specific verb and resource ("Records one entry on a topic") and adds the immediate effect ("reports today's total"), so the agent knows this is a single-entry write with a summary response. However, it never distinguishes itself from the sibling log_entries, which an agent could easily confuse with this tool.

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?

Gives concrete operational guidance: convert the value to the topic's unit first, use occurredAt for backdated entries, and call list_topics first if the topicId is unknown. It lacks any explicit exclusion or comparison against the sibling log_entries, so the when-not-to-use this tool case 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.

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

Annotations already flag destructiveHint=true and readOnlyHint=false, so the bar is lower. The description still adds real value by spelling out the destructive scope (source archived, entries relocated) and an explicit human-confirmation requirement that annotations do not convey. It does not say whether the merge is reversible.

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?

Three short sentences, front-loaded with the core effect before the preconditions and the confirmation policy. No sentence is filler.

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?

With an output schema present, return values need not be explained, and the key constraints (same type/unit, archival side effect, ask the person) are all covered for a two-parameter tool. Only failure behavior and permission requirements are unaddressed.

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?

Schema description coverage is 100% and the schema descriptions ('it is archived afterwards', 'the topic that keeps everything') say the same thing the description does. The description adds no format, constraint, or edge-case detail beyond the schema, so the baseline 3 applies.

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?

Names a specific verb and both resources: it moves every entry from source into target and archives the source. This is more precise than the name 'merge', but it never contrasts itself with adjacent siblings like archive_topic or delete_entry, so sibling differentiation is left to inference.

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?

Gives an explicit precondition (same type and unit) and names the alternative route when the precondition fails (update_topic with unitFactor), plus a confirmation policy. It stops short of stating when NOT to use it, e.g. when a plain archive_topic is what's wanted.

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

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

Annotations declare readOnlyHint=false but destructiveHint=false, so the operation is a non-destructive write. The description adds valuable context beyond that: paused days count like skipped ones, the start can be 7 days back to 60 days ahead, and the pause lasts at most 30 days. These constraints materially affect correct invocation.

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?

Three tight sentences, front-loaded with purpose, then behavioral consequence, then the validity constraints. No filler; the size fits the tool's complexity.

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?

An output schema exists, so return values need not be explained, and annotations cover the safety profile. The description supplies the range/limit rules and the semantic effect on skipped days, leaving little an agent needs but the explicit tie-break against sibling tools.

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?

Schema description coverage is 100%, so 'from', 'to', and 'reason' are fully documented in the schema itself. The description adds no format or edge-case detail beyond what the schema already provides, so the baseline 3 applies.

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 states a specific verb ('Pauses') and resource scope ('every topic over a range of days'), which clearly distinguishes it from the singular sibling skip_day. It doesn't explicitly name an alternative tool, but the 'every topic' scope plus the comparison to skipped days makes its role unambiguous.

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?

Usage context is offered via examples ('a holiday, an illness') and validity windows, but there is no explicit guidance on when to choose pause_days over skip_day or unskip. The conditions for use are implied rather than stated as a routing rule.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavioral context: ordering (newest first), default page size, and the cursor-based paging contract ('pass the previous nextCursor to get the next page'). It doesn't cover permissions or error behavior, but that's minor for a read-only list.

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?

Two sentences, zero waste, with the core behavior (what it lists, ordering, page size) front-loaded before the routing guidance. Every clause carries information.

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?

An output schema exists, so return-value explanation is unnecessary, and the description covers the remaining agent-relevant facts: ordering, pagination mechanics, and the sibling it competes with. Nothing needed to invoke it correctly 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?

Schema description coverage is 100%, so all five parameters (including from/to, limit, cursor, topicId) are already documented in the schema with formats and defaults. The description only restates the default page size and cursor usage, adding no syntax or format meaning beyond what the schema provides — the baseline 3.

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?

States a specific verb (lists), resource (a topic's entries), ordering (newest first), and pagination size (50/page), which distinguishes it from sibling tools like summarize_topic and list_topics without opening a schema.

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?

Explicitly names the alternative for a common intent ('how was my week' → summarize_topic) and states the condition for choosing this tool instead ('find a specific entry or read notes'). Both when-not and when are covered.

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

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

With annotations declaring mutation (readOnlyHint=false, destructiveHint=true), the description adds real context beyond them: the photo never leaves to Dashly, the result is a 'friendly likeness, not a portrait,' and renaming only occurs on request. It stops short of stating that the existing companion is replaced/overwritten, which the destructiveHint implies.

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?

A single front-loaded paragraph that leads with what changes and where, then the branch rules. It is dense but every sentence carries a rule (rename gating, photo privacy, default naming); a little more structure would improve scannability.

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?

An output schema exists, so return values need no explanation. For a 3-param tool with a nested spec object and no required params, the description covers the person-vs-animal paths, privacy handling, and naming rules well; the one gap is not spelling out the replacement/destructive effect on the current companion.

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?

Schema coverage is 67%, and the description compensates usefully: it explains the name parameter's two modes (rename vs. auto-assigned for a new animal like Pip/Bao/Lumi) and that the spec is drawn from fixed lists based on a photo. This adds semantics the schema alone does not convey.

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?

States a specific verb (Changes) and resource (the companion), and goes further to say where it appears: status tile, calendar, and when they log. It also names the concrete values (Pip, Bao, Lumi, or a person) so an agent knows exactly what this tool manipulates.

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?

Gives conditional guidance — 'Pass a name alone to rename it (only when the person asks)' — and a workflow for the person case (look at a shared photo, fill spec from fixed lists). It lacks explicit exclusions against sibling tools, but no sibling touches the companion, so routing ambiguity is low.

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

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

Annotations only declare readOnlyHint=false, destructiveHint=false and openWorldHint=false, which says little about side effects. The description supplies the substantive semantics: a skipped day does not count against the goal and does not break the streak, plus a hard lookback limit of 7 days. That is real behavioral context the annotations do not carry.

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?

Four tight sentences: what it does, the key side-effect guarantee, the scope limit, and the alternative. The primary action and its most surprising property (streak-safe) are front-loaded, and nothing is filler.

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?

An output schema exists, so return values need not be explained. Given a single-required-param mutation, the description covers trigger, side effects, backdating limit, exclusions, and the sibling alternative — everything needed to call it correctly.

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?

Schema description coverage is 100%, including the date format, timezone, default-to-today behavior, and reason phrasing, so the schema already carries the parameter burden. The description adds only the framing that the topic must have a goal and that the reason is the person's own words. Baseline 3 is appropriate.

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?

States a specific verb and resource with scope: 'Takes one day off one topic with a goal.' It also names what it is not (not for tasks) and which sibling covers the broader case (pause_days), so an agent can separate it from unskip and pause_days without opening a schema.

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?

Explicit trigger condition ('when the person says so'), an explicit exclusion ('not for tasks (move their due date instead)'), and a named alternative ('For time off across everything, use pause_days'). Both the when and the when-not are stated rather than implied.

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

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

Annotations already declare a safe read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the exact categories of state reported, the scoring semantics ('5 of 7 on track'), and the rule that weekly/monthly/dated goals show progress but are excluded from the day score.

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 function of the tool and its result shape are front-loaded, and the explanation of per-field rows is load-bearing rather than filler. It is on the dense side, but each sentence carries distinct information.

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?

An output schema exists, so return structure needn't be spelled out, yet the description still characterizes the content usefully. Combined with the annotations it is nearly self-sufficient; only the missing sibling routing keeps it from being fully complete.

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?

With one optional parameter and 100% schema description coverage, the schema already documents the date format and timezone convention. The description adds no parameter-level detail (no examples of interpretation, no note on what 'today' resolves to), so the baseline 3 applies.

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?

States a specific verb and resource ('summarize' + 'a day') and defines the scope precisely: each topic's state, the day score, skips and pauses. It also distinguishes the tool's granularity from a per-topic view by explaining that a field with its own daily goal becomes its own row, which an agent could not infer from the name alone.

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?

Gives concrete usage triggers ('how was my day', 'how am I doing today') and defines what is in versus out of the day score. It does not name the obvious alternative, summarize_topic, or say when to prefer that sibling over this one, so it falls short of explicit routing guidance.

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

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

Annotations already establish the safe read-only profile (readOnlyHint=true, destructiveHint=false), so the description only needs to add nuance. It does so usefully by disclosing that streak and best are computed within the supplied range, which changes how the agent picks a range value. It stops short of return-format or pagination notes, but those are covered by the output schema.

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?

Three tight sentences, front-loaded with the returned metrics and immediately followed by the routing rule and the range caveat. Every clause carries information; nothing is filler.

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?

With an output schema documenting returns and annotations covering the safety profile, the description supplies everything else an agent needs: what is summarized, which sibling to prefer, and the tricky range/streak interaction. Nothing material 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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by explaining the interaction between the range value and the streak metric ('counted within the range, so pass 90d or all'), which is genuine guidance the schema's enum description does not provide.

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 names a specific verb (summarize) and enumerates the exact outputs (totals, today, daily average, streak, best day, goal progress) scoped to a topic over a range. It is instantly distinguishable from siblings like query_entries, which it explicitly contrasts against.

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 states a direct preference rule ('Prefer this over query_entries for "how was my week"'), naming the alternative and the triggering condition. It also gives an actionable hint ('pass 90d or all to find a long streak'), covering when-to-use at a practical level.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows data is deleted. The description adds a genuinely non-structured behavioral requirement — obtain human confirmation before undoing — which is meaningful for a destructive operation. It still doesn't say whether the removal is reversible or what happens to the mark once deleted, keeping it short of a 5.

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?

Two sentences, 16 words, front-loaded with the operation and its identifier source. Every clause carries information; nothing is padded or repeated.

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?

With an output schema present, return values need not be described, and the destructive safety profile is covered by annotations plus the confirmation note. Coverage is nearly complete; only the reversibility/effect of the deletion is left unstated.

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?

Schema coverage is 100% and the schema already explains skipId as 'The skip or pause to remove,' so the baseline would be 3. The description adds provenance the schema lacks — that the id originates from skip_day, pause_days or summarize_day — which tells the agent which values are valid and where to obtain them.

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?

States a specific verb and resource ('Removes a skip or a pause by its id') and goes further by naming the sibling tools that create the ids (skip_day, pause_days, summarize_day). An agent can distinguish this undo tool from skip_day/pause_days without opening any schema.

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?

The source-tool naming implicitly tells the agent this is the undo counterpart to skip_day/pause_days, but there is no explicit 'use this when X, not Y' routing statement or exclusion. The only explicit directive is procedural ('Ask the person first'), which is consent guidance rather than usage routing.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=true, openWorld=false). The description adds real behavioral context beyond them: the change retroactively redefines what 'today' means for all totals and streaks, and invalid input fails with example-bearing errors rather than silently. It stops short of stating reversibility or auth requirements.

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?

Two tight sentences with zero filler; the consequence of the change is front-loaded before the input-format note.

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?

With a single fully documented parameter, an output schema that covers return values, and annotations covering the safety profile, the description carries what remains: impact scope and validation behavior. Only the absence of any note on auth or whether prior entries are re-bucketed keeps it from a 5.

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?

Schema coverage is 100%, so the IANA examples and format are already documented. The description still adds meaning the schema cannot: that the value determines the definition of 'today' for aggregates, and that invalid values are rejected with example output, which tells the agent how failure surfaces.

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?

States a specific verb (changes) and a precise resource (the account timezone), and immediately names the scope of the effect (every total and streak). An agent can distinguish this from get_account and the other update_* siblings without opening the schema.

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?

The description implies when to reach for it (when 'today' should mean something different) and gives a constraint on input format, but never states explicit when-to-use/when-not conditions or points at alternatives. Usage is inferable rather than prescribed.

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

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

Annotations declare the destructive/open-world profile, and the description adds substantial context beyond that: unmentioned content is preserved (patch semantics), a bad patch is rejected wholesale with an error naming the path and allowed values, and the home dashboard enforces an undeletable status card and topic cards. These are behavioral traits an agent could not infer from the annotations alone.

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?

Purpose and patch semantics are front-loaded, and nearly every sentence carries non-redundant guidance (defaults, rejection behavior, home-dashboard constraints). It is dense and somewhat run-on in the middle ('A dashboard document is one wall of cards in order...'), which costs a point on readability rather than on wasted content.

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?

For a nested-patch mutation with an output schema and full annotation coverage, the description covers everything an agent needs: id sourcing, patch vs replace semantics, default widget/size behavior, validation failure mode, and dashboard-size rules. Nothing material is left to inference.

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?

Schema description coverage is 100%, so the baseline is 3, and the description adds genuine meaning: size 'auto' is derived from the widgets, style overrides card color/icon from tiles.icons, theme.density compact tightens tiles, and widgets may be omitted when upserting a card that names a topic (defaults apply). It does not enumerate every nested enum, hence 4 rather than 5.

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 first sentence names a specific verb and resource ("Changes a dashboard's title or document") and immediately reframes 'document' as a patch rather than a replacement, which distinguishes it from create_dashboard and get_dashboard. It also points the agent at the needed sibling data sources (get_dashboard ids, get_capabilities for widgets/draws, update_topic for scene visuals).

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?

Explicit when-to-use and when-not guidance is present: read get_dashboard first and reuse ids, leave size at auto and style alone unless the user asks, keep at most 8 cards and split other themes onto their own dashboard, and on the home dashboard restyle/resize/reorder instead of removing because removal is reverted. These are concrete conditions and alternatives tied to real states.

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

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

Annotations already flag this as a destructive, non-read-only op. The description adds real behavioral context the annotations can't: patch semantics (unsent fields are untouched) and that `values` merges rather than replaces. It stops short of stating reversibility or failure modes for a destructive write.

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?

Three short sentences, front-loaded with the core operation before the mutation semantics and the caution. No filler.

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?

An output schema exists so return values need no explanation, and the partial-update/merge model plus the confirmation caution cover the main risks of a destructive patch tool. It omits cross-tool routing guidance against log_entry and any note on side effects such as reordering when occurredAt changes.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds an undocumented merge rule specific to `values` that materially changes how an agent should populate it. That is genuine semantic value beyond the schema rather than restatement.

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?

States a specific verb+resource ('Corrects an entry') and immediately qualifies the update semantics ('Only the fields you send change'), which separates it from create-style siblings like log_entry. 'Corrects' is slightly idiosyncratic versus the title's 'Update', and no sibling is named, so it falls short of a 5.

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?

Usage is implied: change an existing entry rather than logging a new one, and confirm unmentioned changes with the person. But it never says when to use update_entry instead of delete_entry plus log_entry, nor what prerequisites apply (ownership, entry existence). Guidance is present but incomplete.

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

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.

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.

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.

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.

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.

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.