upload_to_anki

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

With no annotations provided, the description carries full burden but lacks critical behavioral details. It mentions 'upload' and 'convert', implying mutation, but doesn't disclose permissions needed, rate limits, error handling, or whether it creates new cards vs. updates existing ones. The description adds some context (MathJax conversion) but misses key operational traits for a write tool.

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 well-structured with a front-loaded purpose statement followed by a parameter list. Each sentence earns its place by clarifying tool function and parameters. It could be slightly more concise by integrating parameter details into the main text, but overall it's efficient and readable.

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?

Given 5 parameters with 0% schema coverage, no annotations, and an output schema (which reduces need to describe returns), the description does a fair job. It covers parameter purposes and tool function but lacks behavioral context (e.g., side effects, error cases) and doesn't fully address when to use vs. siblings. For a mutation tool with rich siblings, it's adequate but has 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 provides clear semantics for all 5 parameters: 'content' (text with LaTeX conversion), 'deck_name' (target deck), 'card_type' (options explained), 'tags' (purpose stated), and 'anki_api_key' (optional API key). This adds substantial meaning beyond the bare schema, though it doesn't detail format constraints (e.g., LaTeX syntax).

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's purpose with specific verbs ('upload', 'convert') and resources ('flashcards', 'Anki'), and distinguishes it from siblings like 'create_flashcards' (which likely generates but doesn't upload) and 'preview_cards' (which only shows). The mention of 'MathJax conversion' adds specificity beyond basic upload functionality.

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 implies usage context by specifying 'generated flashcards' and mentioning LaTeX conversion, suggesting it's for post-creation upload. However, it doesn't explicitly state when to use this vs. alternatives like 'create_flashcards' (which might handle generation) or 'update_anki_note' (for modifications), nor does it mention prerequisites like AnkiConnect setup.

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