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

Annotations already declare readOnlyHint; the description goes further by stating "Nothing is run", disclosing the authorization profile ("Any project member, viewers included, can read it") and the failure mode ("A dashboard not in this project answers 'Dashboard not found'"). It also clarifies the ambiguous null semantics of refresh (none vs. paused) and where a paused trigger is discoverable.

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 highest-value content (what it returns, and the read-before-update rule) is front-loaded with no filler sentences. The closing trigger paragraph is convoluted — it packs disable/enable/list_triggers and the dashboard:<id> naming convention into one dense run of clauses that takes a second pass to parse.

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?

There is no output schema, so the description carries the entire burden of explaining return values, and it does so field by field, including the distinction between item placement (reportId) and chart content. Permissions, error behavior, and mutation-adjacency are all covered for a two-parameter read 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 description coverage is 100% and both parameters already state their provenance (projectId from fastero_list_projects, dashboardId from fastero_list_dashboards), so the schema does the heavy lifting. The description adds no format, casing, or ID-shape detail beyond that, leaving this at the baseline.

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 ("Read one dashboard's layout and settings") and then enumerates exactly what is returned: name, description, filters, tabs, items, url, refresh. It also draws the line against the two nearest siblings (fastero_list_dashboards omits url and refresh; fastero_get_report covers what a chart shows), 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?

Gives an explicit ordering rule ("Read it before fastero_update_dashboard, whose layout, filters and tabs each replace the whole list") and names the alternatives for adjacent needs: fastero_get_report for chart content, fastero_list_dashboards for a cheap list, fastero_disable_trigger/enable_trigger plus fastero_list_triggers for paused refresh. Each alternative is paired with the condition that selects it.

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