sc_watchlist_add

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

With no annotations provided, the description carries full burden for behavioral disclosure. It correctly indicates this is a write operation via the prerequisite, but does not describe side effects (e.g., whether adding duplicates fails silently or errors, whether it triggers any notifications, or if it requires user confirmation). The description adds value by requiring a write flag, but omits details about mutation consequences. Score 3 for adequate but not comprehensive behavioral coverage.

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 two sentences long, directly front-loaded with the action, and includes critical prerequisite information without any unnecessary words. Every sentence serves a purpose. Score 5 for maximal efficiency.

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 tool is moderately simple (2 parameters, 1 required, no nested objects) and has an output schema. The description covers the essential purpose and a prerequisite but lacks details on parameter semantics and behavioral nuances (e.g., error handling for invalid ISIN, duplicate detection). Given the availability of an output schema, the description could be leaner, but missing parameter explanations and behavioral context reduce completeness. Score 3: adequate but with clear gaps.

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 description coverage is 0%, meaning the description must compensate. However, the description does not explain the parameters 'isin' or 'portfolio_id' beyond their names and types. It adds no meaning about what ISIN represents (e.g., International Securities Identification Number) or the role of portfolio_id (e.g., which watchlist to target if multiple exist). Baseline 3 is appropriate given no parameter info, and the description fails to add value here.

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 states the specific action ('Add a security to the Scalable Capital watchlist'), clearly identifying the verb (add) and resource (watchlist). However, it does not differentiate from sibling tools like sc_watchlist_remove or sc_watchlist (which might be a list view), missing an opportunity to distinguish itself. Score 4 because it's clear but lacks sibling differentiation.

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 includes an explicit prerequisite: 'Requires SC_MCP_ENABLE_WRITES=true', which informs the agent when this tool is usable. It does not specify when to use it versus alternatives like sc_price_alert_add or sc_transaction, but the prerequisite provides context for execution. Score 4 because it offers clear context without explicit exclusions or alternative guidance.

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