How to Use the AI Diagram Analyzer to Auto-Generate Drill Titles, Descriptions, and Tags

Intro

The AI Diagram Analyzer (also called the AI Coach Assistant) turns your canvas drawings into complete drill records in seconds. Instead of manually typing a title, writing coaching points, and picking tags, you can let the AI analyze your diagram and generate all of that for you. This feature saves time, reduces data entry errors, and ensures every drill in your library has consistent metadata.

You’ll use this tool inside the Draw Tool (/draw), which is available to all authenticated users. The analysis covers the diagram’s formation, player movements, and flow, then outputs a suggested title, a step-by-step description, and tags for difficulty, age group, and drill type.

Prerequisites

• An authenticated account with the manage_drills permission (required to save drills).
• A diagram already drawn in the Draw Tool - your canvas must contain at least one player or cone element for the AI to analyze.
• (Optional) Access to the Global Preferences if you want to change the AI model used for analysis. By default, the chain runs Gemini, then OpenAI, then Anthropic.

Step-by-step

1. Open your browser and go to the BallersBook app. Navigate to the Draw Tool by clicking Draw in the top navigation bar (or visit /draw directly).

2. Draw your drill on the canvas. Use the toolbar to add players, cones, balls, arrows, and zones. The AI will analyze the final arrangement, so make sure the positions and movements are clear.

3. Click the Analyze Diagram button (labeled Analyze with AI or simply AI Coach Assistant depending on your club’s version). A loading indicator appears while the AI processes the canvas.

4. Review the AI-generated suggestions in the panel that opens on the right. You will see:

• Suggested Title - A concise name for the drill.
• Step-by-step Description - Coaching points broken into numbered steps.
• Tags - Proposed Age Group, Difficulty, and Drill Type. These are pre-selected but editable.

5. Edit any field you want to change. Click directly in the title or description text boxes, or use the dropdowns to adjust tags. For example, you might refine the title to match your club’s naming convention.

6. Apply the suggestions to your drill by clicking Apply to Drill. This fills the corresponding fields in the drill creation form without saving yet.

7. Go to the drill creation form (if not already open) by clicking Save Drill in the Draw Tool. You will be taken to /drills/new with the title, description, and tags already populated.

8. Adjust remaining fields such as Duration, Image URL (optional), and Diagram Data (already set). Then click Save Drill to add it to your club’s library.

💡 Tip: If you don’t see the Analyze Diagram button, ensure your canvas has at least two elements. The AI requires a minimum amount of input to generate meaningful output.

Tips & Pitfalls

• Smart Fallback Chain - The AI uses a priority list of models (Gemini, OpenAI, Anthropic). If one fails or returns invalid JSON, the next model is tried automatically. You can override this chain in Global Preferences (super-admin only).
• Two-Step Reasoning - By default, the system uses two-step reasoning (twoStepReasoning: true). This means the AI first describes the diagram in plain language, then converts that into a structured output. This often produces better descriptions.
• Guest Users - If you are not logged in, you can still access the Draw Tool and draw a diagram, but the Analyze Diagram button will prompt you to create a free account. Saving requires authentication.
• Inaccurate Tags - The AI may assign a tag that doesn’t match your club’s drill taxonomy. Always review the proposed tags and change them if needed. You can also add custom tags later in the drill editor.
• Canvas Cleanliness - The analysis works best with clear labels and distinct colors. Overlapping elements or tiny objects can confuse the AI. Use the Zoom and Grid Snap features to keep your drawing tidy.
• ⚠️ Warning: If you click Apply to Drill, the form is populated but not saved. You must click Save Drill on the /drills/new page to persist the drill. Closing the browser before saving will lose your changes.

Summary

The AI Diagram Analyzer (AI Coach Assistant) makes it easy to turn a drawn drill into a fully described drill record. After drawing on the canvas, click the Analyze Diagram button, review the AI-generated title, description, and tags, then apply them to the drill creation form. You can edit everything before saving. The feature relies on a smart fallback chain of AI models and supports two-step reasoning for better outputs. Next, you can share the new drill with your coaching staff or use it in a session plan.