Log Plot Hole

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

No annotations are provided, so the description carries the full burden. It conveys that this is a write into a persistent tracking system, but says nothing about required preconditions (active project via story_set_project, story_init), duplicate handling, whether the entry is immutable or later resolved via story_resolve_plot_hole, or what the caller gets back.

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?

A single front-loaded sentence with no filler; every clause (record, new, contradiction/hole, tracking system) contributes to identification of the action.

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 schema fully documents the inputs and there is no output schema to explain, so the description only needs to cover behavior and routing. It remains silent on the lifecycle relationship to story_resolve_plot_hole and on project/init prerequisites, which matters for a mutation tool with zero annotation coverage.

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%, with every one of the four parameters documented in the schema, including an example format for chapters and a default for severity. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.

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 names a specific verb ('Ghi nhận' = record/log) and a specific resource ('điểm mâu thuẫn hoặc lỗ hổng cốt truyện' = plot contradiction/hole), plus the target ('hệ thống theo dõi' = tracking system). The word 'mới' (new) implicitly separates it from the sibling story_resolve_plot_hole, though the sibling is never named explicitly.

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?

Usage is only implied: 'mới' signals this creates a new entry rather than resolving an existing one, which contrasts loosely with story_resolve_plot_hole. There is no explicit statement of when to use this versus story_log_payoff or story_detect_timeline_conflicts (which might surface holes automatically), and no prerequisites such as an active project.

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