Create Tracker workflow

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false and openWorldHint=true, so the safety and mutation profile is covered. The description adds that the created workflow is returned with a generated id and version, plus the precondition that referenced statuses exist, but says nothing about permissions required or side effects of an openWorld write.

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?

Two tight sentences/paragraphs, front-loaded with the purpose and return before the structural requirements. No filler, though the required-field recital slightly overlaps 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 complex nested create with no output schema, the description supplies the required shape, the localization convention, and the status-existence precondition. It omits error/permission behavior, but the annotation set plus rich schema descriptions cover most remaining needs.

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 100%, so the baseline is 3, but the description adds navigational value over a deeply nested body: it flags the three required top-level fields, clarifies that initialAction carries "name and target status", that steps wrap a status plus its actions, and that names are {"ru":…, "en":…} objects. That summary genuinely helps an agent orient in the large schema.

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 opens with a specific verb+resource ("Create a workflow") and even states what the call returns ("with its generated id and version"). It is unambiguously the create operation, but it never names the adjacent siblings (tracker_workflows_update, tracker_workflows_delete, tracker_workflows_list) to sharpen the distinction.

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?

It supplies a real precondition — statuses "must exist" — which is genuine usage guidance. However, it never states when to choose this over tracker_workflows_update or what to do on failure, so usage is only implied by the create verb.

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