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

With annotations only declaring the operation mutates (readOnlyHint=false) without being destructive, the description adds meaningful constraints: organization-wide viewers always receive view-only access regardless of the permission value, and 'private' means creator-only. It also clarifies that the permission setting only governs teammates' access, which an agent could not infer from the schema alone. No contradiction with the 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?

Two front-loaded sentences express the primary action, the reverse action, and the permission model with no wasted words. The parenthetical clarifications ('share', 'creator only', 'also iterate on it') are slightly repetitive but each adds precision rather than padding.

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?

The description covers parameter semantics for the two enums and the resource type, which is the core of calling this tool correctly. It leaves gaps an agent would want for a non-idempotent mutation with no output schema: what the response looks like, who is authorized to publish, and what re-publishing (e.g., switching visibility or permission) does to existing shares.

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 0%, so the description carries the full semantic burden, and it delivers on both enum parameters: it maps visibility values to their real-world meaning (private=creator only, team, organization) and defines permission (view vs edit, plus the org view-only override). artifactId is not elaborated, but its role as the dashboard identifier is obvious from the description and the uuid format in the schema.

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 opens with a specific action pair — 'Publish (share)' and 'revert it to private' — applied to a named resource, the Duvo Pulse dashboard, with explicit scopes (team, organization, creator). This makes the tool's function clearly distinct from dashboard-lifecycle siblings like createPulseDashboard, updatePulseDashboard, and deletePulseDashboard, though it never names an alternative explicitly.

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 implies the trigger condition — an agent should call this when the goal is changing a dashboard's sharing scope — and it usefully covers the unshare case ('revert it to private'). However, it gives no explicit when-not-to-use guidance and does not name alternatives such as updatePulseDashboard for content changes or sendPulseDashboardMessage for targeted distribution, leaving tool selection to inference.

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