ingest_plan

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

With no annotations provided, the description carries the full burden, and it does so excellently. It discloses idempotent merge semantics: untouched epics/stories are preserved, existing story authored fields are refreshed while runtime state is kept, and unrelated manifest keys carry over. It also warns that overwrite=True restores destructive wholesale-replace behavior.

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 first sentence front-loads the verb, resource, and order of operations; the rest supplies necessary edge-case behavior without filler. Though dense, every sentence adds a distinct fact an agent needs to call the tool correctly.

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 stateful, potentially destructive tool with no annotations, the description covers creation order, optional restriction, returned manifest, and re-ingestion behavior. The output schema exists, and the manifest return is still summarized, so no critical invocation context is missing.

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 explains the two non-obvious parameters: only_epics restricts to specific epic summaries, and overwrite toggles old wholesale-replace behavior. plan_name is not explicitly described but is self-evident as the identifier of the saved plan to ingest.

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 specific action and workflow: 'Push a saved plan into Plane. Creates epics first, then issues linked to their parent epic.' This clearly distinguishes ingest_plan from sibling tools like save_plan, decompose_plan, or advance_all_plans, and makes its role unmistakable.

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 intended trigger is clear: after a plan has been saved, this tool pushes it into Plane and optionally restricts ingestion via only_epics. It does not explicitly name sibling alternatives or exclusions, but the context is strong enough for an agent to determine when to call it.

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