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

The description directly contradicts the annotation destructiveHint: true. The description states 'this tool only CREATES a pending proposal; nothing is recorded until confirm_proposal is called,' implying no destructive side effects. However, destructiveHint: true suggests the tool may modify or delete data. This is a significant inconsistency, as the tool appears to be non-destructive and merely stages a proposal. Therefore, the description fails to align with annotations, meriting a score of 1.

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 concise, with the primary purpose stated in the first sentence. The second sentence explains the required follow-up and the MCP note clarifies the non-destructive nature. Every sentence adds value, and the structure is well-organized with the key action and caveat front-loaded. No superfluous text.

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 the two-step flow (propose then confirm), the need for user approval, and the lack of a UI button. It does not explain how to construct the complex spec, but the schema's extensive parameter descriptions compensate for that. The output (proposal ID) is mentioned. Overall, the description provides enough context for an agent to use the tool correctly, though it could have elaborated on error handling or the nature of 'pending proposals'.

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?

The schema has 100% description coverage, with detailed descriptions for the spec and title parameters. The tool description adds no additional parameter semantics beyond what the schema already provides. It does mention the return value (proposal ID) but that is not a parameter. Since the schema fully documents parameters, a baseline score of 3 is appropriate.

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 clearly states the action: 'Propose pinning a filtered insight to the user's Saved Insights tab.' It identifies the specific resource (Saved Insights) and the outcome (a proposal ID). This distinguishes it from sibling tools like confirm_proposal (which records) and list_pending_proposals (which lists), making the purpose unmistakable.

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 gives explicit instructions: after calling this tool, the agent must call confirm_proposal with the returned proposalId upon user approval. It also notes that there is no UI button or proposal card to click, eliminating ambiguity about the required follow-up. This clearly tells the agent when and how to use this tool versus the alternative confirm_proposal.

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