get_shared_view

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

With no annotations supplied, the description carries the full burden and does well: it discloses the permission requirement, the 404 behavior for personal views, and the exact endpoint (GET /api/v1/shared-views/{id}). The main omission is any hint about the response payload beyond 'with its filters,' which matters since there is no output 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?

Short and front-loaded: the core definition comes first, followed by the constraint and the endpoint. The repeated title line ('Get Shared View') and the trailing 'Tags: Views' are low-value padding but not distracting.

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 one-parameter read tool with no output schema, the definition covers the important ground: what is returned conceptually, who can call it, and what happens on a personal view. Only the shape of the returned view object is left unspecified, a minor gap for a tool this simple.

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, which already labels it as the view ID path parameter. The description adds no format, range, or sourcing guidance for that ID, 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 and resource: 'Get Shared View / A single shared view with its filters.' The word 'single' implicitly distinguishes it from the list-style sibling get_all_shared_views, though that sibling is never named. An agent can identify the operation 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 a clear precondition and a negative case: 'A personal view answers 404,' which tells the agent this tool only serves shared views. It also states the required `shared_views:manage` permission. It does not explicitly name alternatives such as get_all_shared_views, so routing is inferred 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.