vk_post_migratio_a1f23411fbe1

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

No annotations exist, so the description must fully disclose behavior. It mentions migration scope and authentication, but it contradicts the input schema by calling the body field 'optional' while schema requires it. It also omits possible side effects, error behavior, or idempotency.

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 reasonably brief and front-loaded, but it contains redundancy: 'Migrate all lists, tasks etc.' is repeated by 'Migrates all projects, tasks, notes...'. Generic proxy boilerplate adds little value.

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?

With only one parameter and no output schema, the description should clearly state the expected result of migration, but it does not. The inconsistency about the body field's optionality undermines completeness, and no return format or async behavior is described.

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?

The schema covers the single body parameter with its own description. The description adds guidance about aliases and body passing, but it incorrectly labels the body as optional and references non-existent path/query parameters, adding confusion rather than clarity.

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 states the tool migrates Todoist data to Vikunja with the explicit endpoint 'POST /migration/todoist/migrate'. It distinguishes itself from sibling migration/get_migratio tools by the action and resource.

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 clear context that this is the migration trigger and explains how to pass the body payload. It does not explicitly contrast with GET migration status tools, but the endpoint and verb make the use case clear.

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