sync_portfolio

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the default 'additive' mode as safest (never deletes), 'mirror' mode requires deletion confirmations, and 'backup' mode treats GitHub as a backup source. It also advises dry-run usage for safety. However, it lacks details on error handling, rate limits, or authentication requirements, which are relevant for a sync operation.

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 appropriately sized and front-loaded, starting with the core purpose. Every sentence adds value: explaining modes, giving safety advice, and directing to alternatives. There is no wasted text, and the structure flows logically from general to specific guidance.

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 complexity of a sync tool with 5 parameters and no annotations or output schema, the description does well to cover purpose, usage guidelines, and key behaviors. It addresses safety with dry-run advice and mode explanations. However, it lacks details on output format, error cases, or authentication needs, which are minor gaps in an otherwise comprehensive description.

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 100%, so the schema already documents all parameters thoroughly. The description adds minimal parameter semantics beyond the schema, such as emphasizing 'additive' as the default for safety and recommending dry_run usage. This meets the baseline of 3, as the schema does the heavy lifting, but the description provides some contextual reinforcement.

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 verb ('sync') and resource ('ALL elements in your local portfolio with your GitHub repository'), making the purpose specific. It distinguishes from sibling 'portfolio_element_manager' by specifying this is for bulk operations versus individual elements, providing clear 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 provides explicit guidance on when to use this tool versus alternatives: it states 'ALWAYS run with dry_run:true first to preview changes' and 'For individual elements, use 'portfolio_element_manager' instead.' This includes both procedural advice and a clear alternative tool, covering when-not scenarios effectively.

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