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

Goes well past the readOnlyHint/destructiveHint annotations by disclosing side-effect absence ('Nothing is run and no widget rows are read'), the exact failure mode ('A page deleted or not in this project answers "Page not found"'), and the permission model ('Any project member, viewers included, can read it'). Those are the auth and error-behavior details an agent cannot infer from 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?

Purpose and payload are front-loaded in the first clause, and the alternative-tool routing follows immediately. It is one dense run-on paragraph packing many clauses (widget fields, error counts, permissions, error string), which is efficient but could be broken up for 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?

With no output schema, the description carries the return-shape burden and does so fully — field names, nested widget structure, and the recentErrors payload with timestamps. Permission scope and the not-found response complete what an agent needs before calling.

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 both parameters already document their provenance (from fastero_list_pages and fastero_list_projects). The description adds only indirect meaning, via the 'not in this project' error case for projectId, so the baseline 3 for schema-covered parameters is right.

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 ('Read one hosted page in full') and immediately enumerates what comes back: HTML, widgets with name and widgetId, url, noteEnabled, refresh, and recentErrors with timestamps. It also explicitly distinguishes itself from fastero_update_page, fastero_list_pages, and fastero_show_page, so an agent can route correctly 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 three alternatives with the exact condition that selects each: update_page replaces the HTML, list_pages lists without it, show_page shows one live without pulling HTML into the conversation. That is an explicit when-to-use / when-not-to-use map rather than implied guidance.

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