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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the additive, non-destructive nature is covered structurally. The description adds nothing beyond that: it doesn't say placement behavior, whether the call returns the created tile or its coordinates, or whether a duplicate tile of the same type is rejected.

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?

One short, front-loaded sentence with zero redundancy, so there is no padding to cut. The problem is the opposite of verbosity: the sentence is sized far below what a mutation tool with a nested payload object 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?

For a write tool with a free-form nested `tile` object, no output schema, and only 50% parameter coverage, the definition should explain where valid tile types come from and what the call yields. None of that is present, so an agent must call it largely blind.

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 50%: the `tile` property carries a genuinely rich description covering defaults and the new-row-at-bottom fallback, but `dashboardId` is documented nowhere. The description neither compensates for that gap nor adds any constraint or format hint beyond 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?

"Add one tile to a dashboard" gives a verb and resource, so the basic action is identifiable, and "one" signals singular-per-call. But it is essentially the tool name and title restated, and it draws no line against update_dashboard_tile, remove_dashboard_tile, create_dashboard, or list_dashboard_tile_types, all of which live in the same sibling set.

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 at all: nothing says when to add versus update an existing tile, whether a tile type must first be discovered via list_dashboard_tile_types, or whether the dashboard must already exist. An agent has to infer the workflow entirely from the tool list.

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