save_analysis

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

With no annotations, the description carries the full burden and does well: it discloses the write target (report tree + complete_report.html) and a non-obvious side effect, that the decision is logged to memory so it is scored after the holding window trades. Missing are overwrite/idempotency behavior, error conditions, and whether the write is atomic — meaningful for a tool that creates files and memory records.

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 primary effect is front-loaded in the first sentence, followed by parameter guidance in a sensible order. Dense but not padded for a 19-parameter tool; a couple of clauses ("so it is scored once its holding window has traded") could be tightened.

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?

For a 19-parameter write tool with no annotations and no output schema, the description covers the main side effects and the two most consequential parameters, but leaves idempotency, return values (report path/id needed to chain into read_report or annotate_report), and the log_decision toggle unexplained. Adequate, not complete.

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 coverage is 0%, so the description must compensate. It explains the two highest-risk parameters well — final_decision is the PM write-up starting with the rating line, and options_analysis/options_strategy/fact_check add optional sections — and the blanket "pass each agent's full text in markdown" covers the many report string params. But log_decision, ticker, and trade_date formats go unmentioned, and the mapping of each named param to its producing agent (bull_case vs aggressive_view, research_plan vs trader_plan) is left implicit across 19 params.

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?

States a concrete verb and resource: save a finished analysis as a report tree (markdown sections plus one complete_report.html) and log the decision to the memory log. That is far more specific than the name alone. It does not, however, name a sibling (annotate_report, list_reports, read_report) to draw the boundary against.

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?

"Save a finished analysis" plus "Pass each agent's full text in markdown" implies the pre-condition that all agent output already exists, and the optional-section sentence tells you when options/fact-check sections appear. There is no explicit when-to-use versus annotate_report, no guidance on when to set log_decision to false, and no statement about re-saving an existing ticker/date.

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