SEO Agent has 9 tools with schemas and descriptions present, but quality is inconsistent. Tool names follow verb_noun convention (search_sites, get_method, build_link, verify_link, log_link, activate, plan_campaign, results). However, descriptions are often vague or domain-specific jargon-heavy without explaining WHEN to use each tool or WHAT the LLM should expect. For example, search_sites description mentions 'locked examples' and 'teaser' concepts without defining them for an LLM unfamiliar with the SEO domain. Parameters have types and basic descriptions, but lack constraints (enums, ranges, patterns). Output schemas are not documented, the code shows what's returned but the tool definitions don't declare expected response structure. Error handling is minimal; no recovery guidance or actionable error messages visible. Security concern: activate() accepts an API key as a parameter, violating secret-injection pattern.

• Move API key from activate() parameter to environment variable (SEOAGENT_API_KEY) or secure vault. The code already reads from env, use that exclusively and remove the parameter.
• Expand tool descriptions to 100-200 chars, explaining WHEN to use each tool. E.g., search_sites: 'Search the free link library by keyword, DA, or method. Returns free matches and a preview of locked sites (subscription required). Use this first to explore available sites for a campaign.'
• Add output schema documentation to each tool. E.g., search_sites returns {free: [{slug, name, domain, da, dofollow, method, auto_build}], free_total: int, locked_examples: [...], full_library: {sites, reachable, by_da}, upgrade: {...}, ask_the_user: string}.
• Add enum constraints to parameters: status in log_link must be one of ['placed', 'unverified', 'manual', 'failed']. Add ranges: min_da 0-100, limit 1-100, count 1-500.
• Implement error recovery guidance. When activate() fails, return: {error: 'Invalid API key', recovery: 'Verify the key from your subscription email. If you don't have a subscription, call search_sites() to explore free options or visit {BUY_URL}.'}