create_co_scientist_final_report

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

With no annotations provided, the description carries the full burden of disclosing side effects. It does this well by noting that the tool creates one co_scientist_report artifact and compact session summaries, and that mark_complete can move the run phase to complete. This gives the agent a meaningful behavioral picture beyond just 'create a report.'

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 well-organized with clear sections for triggers, workflow position, and parameters. Every section earns its place, and the core purpose is front-loaded. It is detailed but not bloated.

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 no annotations and no output schema, the description covers prerequisites, side effects, parameters, and workflow context well. It is missing only minor details such as what the returned artifact reference looks like or the behavior when mark_complete is false, but the provided information is sufficient for an agent to invoke the tool correctly.

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 must compensate. It provides a PARAMETERS section explaining run_id, created_by, and mark_complete, including the side effect that mark_complete moves the run phase to complete. This adds meaning beyond the raw schema, though run_id could include more detail on where to obtain or validate the run ID.

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 a specific verb and resource: 'Create the final Co-Scientist report artifact for a verified run.' This clearly differentiates it from sibling tools like get_co_scientist_report (retrieval) and export_co_scientist_findings (export), since this tool creates a durable report artifact.

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 explicitly lists automatic triggers and workflow position: after submit_verification has completed for every selected hypothesis, when the user asks for the final report, or before export/memory preservation. It tells the agent exactly when this tool should be called relative to other workflow steps.

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