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

Goes well beyond the readOnly/non-destructive annotations: it discloses what is returned (share URL, share id, title, access), that private and hidden reports render for their owner via a report-scoped one-hour viewer token, and the exact degradation path (URL only) when viewer-token signing is unconfigured. That auth and fallback detail is exactly the context an agent cannot infer from structured fields.

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 sentences, front-loaded with the core rendering behavior, then call construction, then return values, then the edge case. Each sentence carries non-redundant information, including the return-shape sentence, which is justified because no output schema exists.

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?

Complete for a read-only viewer tool with no output schema: purpose, parameter provenance, return payload, and the private/hidden-report permission and token-lifetime edge case are all covered. Nothing material 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?

With 100% schema description coverage, the schema already documents all three parameters, and the description largely restates provenance for viewId and pageId. It adds a small amount of meaning ('open first' for pageId) but says nothing about clientId or the accepted view_<hex>/hex formats beyond what the schema provides.

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 (shows a Jepto report inline as an interactive MCP App) and clarifies the rendering mode — same page tabs and live cards as the share link — which is the key distinction from data-fetching siblings like report_get or view_card. It never names an alternative explicitly, so the differentiation is implied rather than spelled out.

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 provenance guidance: viewId comes from report_create or report_get, and pageId selects which page opens first. That tells the agent how to assemble a valid call, but there is no explicit when-not or named-alternative routing (e.g., use report_get instead when you need raw JSON rather than a rendered view).

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