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

Annotations only indicate non-read-only, non-idempotent, non-destructive behavior. The description goes far beyond this by explaining the permission model (members may read/list/execute, owner may revise/re-share/delete), execution semantics (runs against reader's tickets, shares question not answers), re-sharing behavior (moves, not duplicates, max one team), and authentication/scope requirements. This is rich, valuable context.

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 description is succinct but information-dense. Four sentences cover the core action, permissions, execution behavior, and an important practical limitation. Every sentence earns its place without redundancy or filler.

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?

Given the tool's moderate complexity, the description thoroughly explains what sharing means, how it behaves for the reader, the single-team constraint, and the team ID discovery issue. It also notes required scope, and with an output schema present, it does not need to detail return values. The description provides complete context for correct usage.

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 already provides 100% coverage for both parameters. The description adds value by clarifying that view_id comes from list_saved_views, team_id must be a team you belong to, and team IDs are not discoverable from this MCP surface—practical guidance beyond the schema descriptions.

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?

The description begins with 'Share one of YOUR OWN saved views with a single team you belong to,' which clearly identifies the verb (share), resource (saved view), and recipient scope (a single team). It also distinguishes this tool from siblings like archive_saved_view, delete_saved_view, and unshare_saved_view by stating it is specifically for sharing.

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?

The description clearly implies when to use the tool (when you want to share your own saved view with a team) and provides critical usage nuances, such as re-sharing moves the view and team IDs are not discoverable. However, it does not explicitly name alternative tools for related operations (e.g., unshare_saved_view), though the context is strong.

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