Dashly

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuine context beyond that: what actually gets destroyed (paired screens lose the dashboard and are removed), the Home restriction, and an explicit confirmation requirement.

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 clauses, front-loaded with the verb and its effect, then the constraint, then the caution. No filler and nothing important buried at the end.

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 description covers the destructive semantics, the Home exclusion, and the confirmation requirement. What remains slightly ambiguous is whether the paired screens themselves are deleted or merely unlinked, but the operational picture is otherwise 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?

Only one parameter, and schema description coverage is 100% – the schema already documents dashboardId as a uuid sourced from list_dashboards. The description adds nothing further 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 (archives/hides) and resource (custom dashboard), then explains the concrete effect: every screen paired to it stops showing it. This clearly separates it from update_dashboard and delete_entry, so an agent can pick it without opening other schemas.

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 a real exclusion ('Home cannot be archived') and a procedural prerequisite ('Ask the person first'), which is exactly the guidance an agent needs before invoking a destructive tool. It does not name a sibling alternative, but none is obviously needed for this operation.

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 idempotentHint=true, so the safety profile is partly covered. The description goes beyond them by spelling out the concrete side effects (removal from lists, cards stripped from dashboards) and the need for human confirmation, though it does not say whether the action is reversible or undoable.

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, each doing distinct work: effect, routing rule, and confirmation requirement. The primary effect is front-loaded and there is 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 not be explained, and annotations cover the destructive/idempotent profile. Combined with the explicit side-effect description and the alternative-tool routing, an agent has everything needed to decide and invoke 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?

There is a single parameter with 100% schema description coverage, including its UUID format and the source tool ('from list_topics'). The description adds no parameter-level detail, so the baseline 3 applies since the schema carries the full burden.

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 specific verb (removes/archives) and resource (topic), and explicitly scopes the effect: the topic leaves the person's lists and its cards come off dashboards. It is distinguishable from the sibling update_dashboard, which is named as the tool for a different need.

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 the condition for use ('Only for a topic the person no longer tracks') and the exclusion with a named alternative ('to take a topic off home or another dashboard, remove its card with update_dashboard instead'). It also adds a required confirmation step ('Ask the person first'), 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 only declare write/safety flags; the description adds substantive behavior: optional document (starts empty without one), a hard limit of 3 non-home dashboards, plan gating with named error codes (PLAN_REQUIRED, DASHBOARD_LIMIT_REACHED), and that validation errors name the offending path and allowed values. This is genuine value beyond the structured hints.

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?

Front-loaded with the core action and mostly information-dense, with no filler sentences. The middle clause chain (size/style/scene/density) is semicolon-heavy and reads as a run-on, which slightly hurts 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?

For a creation tool with a rich nested schema and an output schema, the description covers the pieces an agent needs: empty-start behavior, plan/limit failure modes with exact error codes, validation error shape, and the follow-up path. Nothing essential 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% and enum lists already live in the schema, but the description adds meaning the schema cannot: that size 'auto' is a computed default derived from the widgets, that style overrides card color/icon from tiles.icons, that scene comes from update_topic, and that theme.density compact tightens tiles. That lifts it above 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 and resource ('Creates a dashboard besides home') and immediately scopes it against the built-in home dashboard and against update_dashboard for adding cards. An agent can distinguish it from archive_dashboard/list_dashboards/update_dashboard without reading schemas.

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 routes follow-up work to update_dashboard ('Add cards afterwards with update_dashboard') and points to get_capabilities (tiles.draws) for widget/type constraints, plus a design norm ('one dashboard per theme'). No explicit when-not-to-use beyond plan gating, so it stops just short of the top band.

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 write semantics (readOnlyHint=false, idempotentHint=false, destructiveHint=false), so the bar is lower. The description adds real non-schema behavior: a new topic's tile lands on home by itself and appears elsewhere only via update_dashboard, colour is auto-assigned when omitted, and units must be normalized ('pick one unit and keep every value in it'). No permissions or failure modes are covered, hence not 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?

Front-loads the core action, then dedup guidance, then the type taxonomy. Most sentences earn their place, but the long inline type enumeration duplicates the enum's own descriptions and pushes the important 'list first' guidance into a mid-paragraph position.

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 tool with nested oneOf goals and 20+ sibling tools, the description covers purpose, dedup workflow and cross-tool routing, and an output schema exists so return values need not be explained. It leaves the goal/scale/fields structure entirely to the schema, which is acceptable given 100% schema coverage.

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 property descriptions are extremely detailed (goal shapes, type semantics, unit rules, colour, polarity), so the schema already carries parameter meaning. The description largely restates this (its type list even omits 'rating'), so baseline 3 is correct.

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 concrete creation verb and resource ('Creates something to track', a topic) and immediately distinguishes it from siblings by naming list_topics (reuse) and update_dashboard (adding a card elsewhere). The full type taxonomy makes the artifact this produces 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?

Gives an explicit precondition/alternative: 'List topics first and reuse a matching one' tells the agent when not to call this tool. It also routes a related need (placing a tile on another dashboard) to update_dashboard, so the agent knows where the boundary of this tool lies.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds a behavioral requirement annotations cannot express - human confirmation before execution - which materially changes how an agent should invoke it. It still omits whether the deletion is permanent or recoverable, so not 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 short sentences, zero filler, and the action is front-loaded ahead of the confirmation instruction. Nothing could be removed without losing 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 and annotations cover destructiveness and idempotency, so the description need not explain returns. What it does not address is whether the deletion is irreversible and what happens to data associated with the entry (e.g., its log records), which matters for a destructive, open-world operation. Adequate but with a clear gap.

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 single entryId parameter is documented as 'The entry to delete.' with a uuid format. The description adds nothing beyond the schema, so the baseline 3 applies rather than a higher score.

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 one entry'), and the singular scope ('one') is precise enough that an agent knows this deletes a single record by id rather than bulk-deleting. It does not differentiate from sibling archive_topic/archive_dashboard, which is the only missing element for 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?

'Ask the person first' establishes a confirmation prerequisite before invocation, which is genuine usage guidance. However it offers no alternatives (e.g., whether archive is a non-destructive substitute) and no explicit when-not-to-use condition, so it remains implied rather than complete.

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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description contributes only content scope (fair-use limit comparison, token count) and says nothing about auth requirements or staleness/caching of the returned figures.

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 sentence with no filler, and the most salient items (email, timezone, billing state) are front-loaded. It is slightly weakened by being a noun-phrase inventory with no leading verb to anchor the action.

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 zero parameters, full annotation coverage, and an output schema present, the description need not explain return shape, and it does confirm the scope of what is returned. It is adequate for a simple read tool, with the only real gap being routing guidance versus update_account.

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, which is the baseline-4 case; there is nothing for the description to disambiguate. The field list it provides is about output content, not inputs, so it neither helps nor hurts here.

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 exactly what the tool surfaces (email, timezone, subscription/billing state, fair-use usage, personal token count), so an agent can tell it reads the caller's own account snapshot. It never states a verb like 'retrieve' and never contrasts with the sibling update_account, so it is clear but not sibling-differentiating.

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?

No when-to-use guidance and no mention of alternatives such as update_account or get_capabilities. The agent must infer from the name alone that this is the read path for account state.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond the annotations: the payload is identical for all users and immutable within a conversation, which tells the agent caching/reuse is safe. It does not mention payload size or any truncation behavior, keeping it 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 sentences, front-loaded with the payload enumeration and closed with the reuse instruction. Minimal waste, though 'It is the same for everyone' and 'does not change during a conversation' are two clauses carrying nearly the same caching point and could be merged.

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 documentation is not the description's burden, and it nonetheless previews the returned content accurately. With no parameters and annotations covering safety, an agent has everything needed to call this correctly and know when not to call it again.

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?

Zero parameters, so there is nothing for the description to disambiguate and the baseline 4 applies. The description also correctly implies the tool takes no filtering arguments, since the content is described as fixed for everyone.

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 exactly what the tool yields: topic types, allowed widget kinds per topic type, card sizes and their rendering, ranges, plans and theme options. That is far more specific than the bare title 'Get capabilities' and clearly separates it from every mutation sibling (create_*/update_*/archive_*). It stops just short of 5 because it never states the action verb plainly (e.g. 'returns a static catalog'), relying on the reader to infer that this is the read that produces those things.

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 explicit timing and cadence: read once, before the first dashboard change, then reuse. It also names the equivalent resource (dashly://capabilities) so an agent knows there is an alternative access path rather than a second tool call to make. No ambiguity about when this should be invoked.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful domain context about what the returned document contains (card ordering, size options, style overrides, density), but says nothing about pagination, response shape limits, or access requirements beyond that.

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 purpose is correctly front-loaded in the first sentence, but the remainder is a dense, semicolon-chained block of domain model detail (size, style, scene, density) for a one-parameter getter. The content is relevant but overstuffed relative to what an agent needs to invoke the tool.

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, the description need not restate return values, and it instead supplies the conceptual model needed to interpret the document, plus a pointer to get_capabilities. That covers the essentials for a read-only getter, leaving only minor gaps around response limits.

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 single dashboardId parameter is fully documented in the schema ('from list_dashboards'), so the description adds no parameter meaning. Baseline 3 applies 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 opening sentence states a specific verb and resource ('Returns one dashboard and its full document'), which is immediately distinguishable from list_dashboards. It never explicitly names a sibling, but the singular scope makes the retrieval role clear.

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 a contextual cue that this precedes update_dashboard, and it routes the agent to get_capabilities (tiles.draws) for widget details. However, there is no explicit statement of when to prefer this over list_dashboards or other readers, so usage is only 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 readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds behavior the annotations cannot: the ordering rule ('home first'), the kind taxonomy, and the fact that the url is the person's own link that only resolves after 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 sentences, no filler. The scoping/return information is front-loaded and the usage instruction follows, so the agent gets purpose before procedure.

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 and the description wisely does not re-document the full return payload, yet it still names the key fields and the sign-in caveat on the url. For a no-param, read-only, closed-world list tool this is essentially complete; only the absence of a pointer to get_dashboard for single-dashboard lookups is a minor omission.

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 nothing for the description to disambiguate. It correctly avoids inventing filtering options that the schema does not support.

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 goes further by enumerating the returned fields (id, kind, title, url), which makes it unambiguous versus the singular get_dashboard sibling. An agent can tell it is a collection read, not a single-item fetch, 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?

Gives an explicit trigger: 'Call this when the person asks to see a dashboard and give them its url.' It also clarifies the follow-through action (hand the person the url). It does not name the alternative to use when only one known dashboard is wanted (get_dashboard), so no when-not guidance is present.

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, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds real context beyond that: it acts as a bootstrap call whose ids should be cached, and it discloses the cross-tool constraint that values must be expressed in the topic's `unit` before logging.

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 is returned, then the call-once/cache instruction, then the unit-conversion caveat. No filler and no restatement 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?

An output schema exists, so return values need not be re-specified, yet the description still orients the agent on the fields and adds the workflow guidance (call once, reuse, normalize units) that the schema and annotations cannot convey. Nothing needed to call 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?

The tool takes no parameters, so there is nothing to disambiguate and the baseline for a zero-parameter schema applies. The description correctly adds no parameter discussion and instead spends its words on usage.

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 specific verb and resource ('Lists everything the person tracks') and enumerates exactly what each topic record contains (id, type, unit, goal, entry count, last entry time). This makes it immediately distinguishable from list_dashboards and from the entry-oriented siblings.

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 when to call ('once at the start') and gives a decision rule that steers the agent away from create_topic ('reuse a topic that already fits instead of creating a near-duplicate'). It stops short of naming create_topic or update_topic as explicit alternatives, so the routing is implied rather than spelled out.

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=false, destructive=false, openWorld=true, idempotent=false, so the safety profile is covered. The description adds real value beyond them: all-or-nothing atomicity and the fact that the error identifies the offending entry, which materially affects how an agent should retry or split a batch.

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 capability, then the atomicity constraint, then the sibling routing. Every sentence carries distinct information with no repetition of the title or schema.

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 batch tool with an output schema, the description covers the operation, its limit, its failure semantics, and its relationship to log_entry. 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 coverage is 100% and the nested entries schema documents note, tags, value, values, topicId and occurredAt in detail, so the schema does the heavy lifting. The description only restates the 50-item cap that maxItems already encodes and adds example scenarios, so 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?

The description gives a specific verb (records), resource (entries), and scope (up to 50 in one call), then distinguishes the tool from its sibling by naming log_entry explicitly. An agent can tell immediately that this is the batch variant of log_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?

"Prefer this over repeated log_entry calls" names the alternative and the condition that selects it, and the meal/backlog examples make the intended batch use concrete. There is no explicit statement of when not to use it (e.g., for a single entry), so it falls short of a full when/when-not treatment.

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 safety profile (write, non-idempotent, non-destructive, open-world). The description adds real behavioral content beyond that: the value must be pre-converted to the topic's unit, and the call reports today's total. No auth, rate-limit, or failure behavior is disclosed, but the added context is material.

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, front-loaded sentences with no filler - the core action leads, followed by the two most error-prone guidance points and the prerequisite. Every sentence 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?

For a six-parameter write tool with a full output schema, the description covers the essential gotchas (unit conversion, backdating, topic id prerequisite). Remaining detail on note/tags/values lives in the schema, so nothing critical is missing, though how to find a topic's unit could be spelled out.

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 schema already documents value conversion ('2 litres is 2000 for a ml topic'), occurredAt semantics, and the required note field. The description's conversion and occurredAt sentences largely restate schema content, adding workflow framing but little new 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 one entry on a topic' - and the singular 'one entry' implicitly separates it from the batch sibling log_entries. However, it never names that sibling, so the differentiation must be inferred from the plural tool name rather than stated.

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 context: call list_topics first if the topic id is unknown, use occurredAt for backdated entries, and convert values before logging. It stops short of naming alternatives (e.g. log_entries for multiple entries, update_entry for corrections).

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 destructive=true and idempotent=true, but the description adds what actually happens to data (all entries are moved, the source is archived rather than deleted) and the type/unit compatibility constraint. The human-confirmation requirement is behavior an agent cannot infer from 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, front-loaded with the effect, then the precondition, then the confirmation requirement. Every sentence changes how the agent would call the tool; nothing is padding.

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 described. For a destructive merge, the description covers effect, precondition, alternative path, and the need for human approval — everything an agent needs to invoke it safely.

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%: sourceId and targetId are both documented in the schema, including the fact that sourceId gets archived. The description adds no format or identifier detail beyond that, so the schema carries the load and a 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 (merge/move) and resource (topics), and spells out the full effect: entries move to the target and the source is archived. This clearly distinguishes it from archive_topic and update_topic, which are the nearest siblings.

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 routes the agent to the alternative path when it fails: convert first with update_topic and unitFactor. It also adds a confirmation requirement ('Ask the person first'), so the agent knows both when to call it and when to hold back.

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 a non-read-only, non-destructive, non-idempotent mutation, but the description adds substantive behavior the annotations cannot convey: the valid start window (7 days back to 60 days ahead), the 30-day maximum duration, and the semantic equivalence between paused and skipped days. It omits what happens on invalid ranges or how pauses interact with already-logged entries.

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 action and effect, then the constraints. Every clause carries information (use cases, skip equivalence, valid window) with 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 annotations cover the safety profile. With the description supplying scope, window limits, and duration cap, an agent has everything needed to call this 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 coverage is 100%, so from/to/reason are documented in the schema (including the 'same as from for one day' case). The description adds constraint meaning to from/to that the schema lacks: the allowed 7-days-back / 60-days-ahead start window and the 30-day maximum span.

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 (pauses) and resource (every topic) with explicit scope, and the title/description agree that the action applies across all topics rather than one. An agent can distinguish it from skip_day (single day) and archive_topic 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?

Gives concrete use cases (holiday, illness) and relates the effect to skipping via 'Paused days count like skipped ones,' which implies the alternative semantics. It stops short of explicitly naming skip_day/unskip as alternatives or stating exclusions, so it is clear context rather than 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 cover the safety profile (readOnly, idempotent, non-destructive), so the description only needs to add context. It adds real behavioral detail: newest-first ordering, default page size of 50, and the cursor mechanism for continuing. It stops short of describing return shape, but an output schema exists.

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: the read operation and ordering first, pagination next, alternative-tool routing last. No filler and nothing that repeats the schema verbatim.

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 paginated list tool with full schema coverage, annotations, and an output schema, the description covers the gaps that matter (ordering, page size, cursor chaining, tool choice). Nothing an agent needs to call 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 coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema by explaining the cursor's role ('pass the previous nextCursor to get the next page') and how pagination chains across calls, plus the default page size that governs limit usage.

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) and resource (a topic's entries) with ordering and page size, which no sibling schema needs to be opened to understand. It also explicitly names summarize_topic as the other tool, so the agent can tell them apart.

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 both when-to-use ('find a specific entry or read notes') and when-not-to-use with a concrete example ('how was my week' -> summarize_topic). The alternative is named explicitly 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 idempotentHint=true, so the description's job is to add context — and it does: the shared photo never goes to Dashly, the output is a friendly likeness rather than a portrait, and an unnamed new animal auto-gets a default name. It does not spell out that setting a companion replaces/overwrites the existing one, which is the main remaining behavioral gap for a destructive tool.

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 dense sentences, front-loaded with what the tool changes before the mode-specific rules. All sentences carry information an agent needs (rename rule, photo handling, default naming). Slightly heavy, but nothing is redundant.

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 described. The description covers the two operating modes, the privacy-sensitive photo path, the naming defaults, and the spec sourcing, which together with the nested schema is enough for an agent to call this 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 coverage is 67% and three params exist, so the schema does substantial work. The description still adds real semantics beyond it: 'name alone' means rename, spec must be filled from the fixed lists, and the animal kinds carry default names (Pip, Bao, Lumi). It does not clarify required-vs-optional spec fields for the person kind, but overall it compensates for the partial schema coverage.

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 (set/change the companion) and immediately explains what the companion is and where it surfaces (status tile, calendar, logging). The named characters and the person option make the scope concrete, and no sibling tool touches this resource, so it is trivially distinguishable from the dashboard/topic/entry tools.

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 mode-level guidance: pass a name alone to rename '(only when the person asks)', and use the photo-and-spec path when the companion is a person. It does not name an alternative tool, but no sibling overlaps this resource, so there is nothing to exclude. Clear context without explicit when-not rules.

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 cover the safety profile (idempotent, non-destructive, non-read-only), and the description adds genuine domain behavior: a skipped day does not count against the goal and does not break the streak, and only up to 7 days back. That is real context beyond structured fields. It could say more about re-skipping or what the streak/goal state looks like afterward, but the output schema covers return values.

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 tightly packed sentences, front-loaded with the core purpose, then the behavioral rule, then the boundary conditions and the sibling pointer. No filler; 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?

For a 3-param mutation with full schema coverage, annotations, and an output schema, nothing an agent needs to select and call it correctly is missing: purpose, trigger, exceptions, window, and sibling routing 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?

Schema coverage is 100%, so the schema already documents day, reason, and topicId including formats and the today-default. The description adds no syntax or format detail beyond that, so the baseline of 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+resource+scope ('takes one day off one topic with a goal') and explicitly carves out what it is not: not for tasks, not organization-wide. An agent can distinguish it from pause_days and unskip without reading 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?

Gives the triggering condition with a natural-language example ('skip stretching today, my back hurts'), names the exclusion (tasks -> move their due date), and routes to the alternative (pause_days for time off across everything). When/when-not/alternatives are all present.

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 a read-only, idempotent, non-destructive call, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: how the score is computed, that a field with a daily goal becomes its own row (e.g. "Food · Protein"), and that weekly/monthly/dated goals appear 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?

Front-loaded with what the summary contains, then scoring rules, then usage triggers. It is dense but nearly every clause carries information; the field-row explanation is the longest piece but justified by the non-obvious scoring behavior it clarifies.

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 formatting need not be described, yet the description goes further by explaining the semantics behind the score and row layout that a schema cannot convey. Combined with a fully documented parameter, an agent has enough to call it correctly; only explicit sibling routing 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 single `day` parameter is fully documented in the schema (format, timezone, default of today). The description adds nothing further about the parameter, so the baseline of 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+resource and details the scope: per-topic state across everything the person tracks, plus the day score. It implicitly separates itself from summarize_topic by scoping to the whole day ('across everything the person tracks'), but never names the sibling, leaving a small ambiguity risk given the near-identical name.

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 explicit trigger phrases for when to use it: "how was my day" or "how am I doing today". There is no stated when-not or named alternative, 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 establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds a genuinely non-obvious behavioral trait: streak and best are computed only within the requested range, so a short range truncates a long streak. That nuance is not derivable from the annotations or 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?

Two sentences with no filler: the first front-loads the outputs, the second handles routing and the range/streak caveat. Every clause carries information an agent needs.

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 annotations cover the safety profile. The description still supplies the output inventory, the sibling routing rule, and the range/streak interaction, leaving nothing material missing 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?

Schema coverage is 100%, so baseline is 3. The description goes beyond the schema's terse 'window to cover' by explaining that the range bounds the streak/best calculations, giving semantic weight to the range parameter and concrete value guidance (90d, all). The field parameter, however, is left entirely to the 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 exact computed outputs (totals, today, daily average, streak, best day, goal progress) for a specific resource (a topic over a range), so the agent knows precisely what it returns rather than a generic 'summary'. It also explicitly contrasts itself with the sibling query_entries, making it distinguishable 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?

It names the alternative (query_entries) and the exact query pattern that should route here ('how was my week'), then adds a concrete usage rule for the streak use case (pass 90d or all). Both when-to-use and how-to-use are explicit.

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, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds two things the annotations cannot: where the identifier originates and a mandatory human-confirmation step, which is meaningful for a destructive operation. It stops short of describing the resulting state (e.g. whether entries logged during the skip are affected).

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 clauses, no filler: the action and its id provenance come first, the safety directive second. Every word earns its place and nothing an agent needs is buried.

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 one fully documented parameter, an output schema handling return values, and annotations covering the destructive/idempotent profile, the description is nearly complete. Only the post-removal effect on the underlying day is unstated, which is a minor gap for a single-id undo tool.

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 real value by enumerating the three producer tools the uuid must be drawn from — information absent from the schema's generic 'The skip or pause to remove.'

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?

Specific verb ('Removes') plus specific resource ('a skip or a pause'), scoped by id. It goes further than the name by naming the exact sibling tools that produce the ids (skip_day, pause_days, summarize_day), so an agent can place it in the workflow 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 description establishes the precondition for use — the id must come from skip_day, pause_days, or summarize_day — and adds an explicit confirmation rule ('Ask the person first'). It does not name a when-not case or a sibling alternative (e.g. re-skipping instead of unskipping), which keeps it short of a 5.

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, idempotentHint=true, and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the change has account-wide consequences for totals and streaks, and invalid input is rejected with concrete examples, which tells an agent how to recover from a failed call.

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: impact is front-loaded, the input constraint follows. No filler, no restatement 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 single-required-parameter mutation with an output schema and full annotations, the description supplies the effect, the input format, and the failure mode. It does not address whether access is restricted or whether historical data is re-bucketed, minor gaps for a destructive account-level change.

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 names the format as an IANA timezone with four concrete examples. The description repeats the IANA requirement, adding only that invalid names are rejected (with examples), which is a small increment over what structured data provides. 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 ('Changes the account timezone') and immediately scopes the effect to every total and streak, which separates it from the many update_* siblings that touch dashboards, entries, or topics rather than the account itself.

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 explicit 'use when/when not' clause, but the description of the downstream effect (timezone decides what 'today' means for all totals and streaks) implicitly signals when this setting matters. With no real alternative tool for account-level timezone changes, the absence of sibling routing is a modest gap rather than a serious one.

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 mutation/destructiveness/idempotency, and the description adds behavior they cannot express: atomic all-or-nothing rejection with path-and-allowed-values errors, patch-not-replacement semantics, default widget inheritance when a topic is named, and the 8-card ceiling. This is exactly the extra context annotations leave out.

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?

Front-loaded with the core action, then layered detail; each sentence mostly earns its place for a deeply nested patch schema. A few clauses (theme.density compact, the tile/scene aside) drift into adjacent topics and could be trimmed without loss.

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 3-parameter tool with a deeply nested document schema and an output schema, the description covers patch semantics, defaults, error behavior, size limits and cross-tool routing. Nothing needed to call it correctly is missing, and return values are rightly left to the output schema.

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 real meaning: why size defaults to auto, that style overrides card color/icon, what theme.density compact does, and that widgets are optional when a topic is named. It stops short of explaining move-index or theme fields, so it exceeds baseline without being exhaustive.

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 ("Changes a dashboard's title or document") and immediately qualifies the scope with patch semantics ("upsert or remove cards by id ... everything you do not mention stays"). This lets an agent distinguish it from create_dashboard, archive_dashboard and get_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?

Names alternatives explicitly and conditions for each: read get_dashboard first for ids, use get_capabilities for widget/size behavior, use update_topic for a topic's tile scene, and an explicit when-not ("never archive the topic for that" when removing a card from home). It also routes non-matching work elsewhere ("put other themes on their own dashboard").

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, idempotentHint, readOnlyHint=false, so the safety profile is covered. The description adds genuinely non-obvious merge semantics ('only the fields you send change; values merges into the existing values'), which is the key behavioral fact an agent needs. It does not say what a destructive change overwrites or how errors surface.

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, purpose first, then the non-obvious merge rule, then the caution. No filler and nothing buried.

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 schema is rich enough to carry field-level requirements. Nothing critical is missing for a partial-update tool, though a note on what a destructive overwrite replaces would round it out.

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 schema already documents all six parameters in detail, giving a baseline of 3. The merge note for `values` adds marginal meaning beyond the schema's own field description, but no other parameter semantics are clarified.

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 ('Corrects an entry'), which separates it from create/log/archive/delete siblings. It does not explicitly name any alternative, so it falls short of the 5 bar for sibling differentiation.

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?

Implies usage (use this to correct an existing entry) and adds one real guideline: ask the person before changing something they did not mention. However, it gives no routing versus delete_entry or log_entry, and no precondition such as obtaining entryId from query_entries.

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 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.

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.

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.

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.

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.

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.