Update research project status

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

With no annotations provided, the description carries the burden of behavioral disclosure. It does reveal important behavior around merge mode (preserving and de-duplicating history) and replace mode (intentional full replacement). However, it does not disclose side effects for unknown projects, whether fields are overwritten individually or as a whole, or any broader impact beyond the status record.

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 compact and front-loaded: it states what is persisted, then explains mode behavior. The third sentence about merge_mode values is slightly redundant with the schema enum, but still useful for quick agent parsing without inspecting the schema.

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 7-parameter mutation tool with no annotations, the description is functional but not complete. It lacks guidance on whether the project must already exist, how to format list-like fields (string vs array), and how replace mode affects unspecified optional fields. The presence of an output schema helps, but the description alone leaves notable call-semantics 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?

Schema description coverage is 0%, so the description must compensate. It does connect the main fields (stage, completed work, pending work, risks, decisions) to their conceptual meanings and explicitly states merge_mode values. Yet it does not clarify the string-or-array flexibility, the meaning of null defaults, or the semantics of project_name matching, which the schema alone does not fully explain either.

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 specifies a concrete action ('Persist') and the resource ('current research project stage, completed work, pending work, risks, and important decisions'). It is distinguishable from related read tools like get_project_status, though it does not explicitly differentiate itself from update_candidate_status or record_research_activity.

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 useful guidance on when to use merge mode versus replace mode, including the de-duplication and full-replacement behaviors. However, it does not explain when this tool should be chosen over sibling tools such as record_research_activity or get_project_status, leaving some usage context implied rather than explicit.

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