feat: Add comprehensive .describe() annotations to all Zod schemas (82 parameters)

[triepod-ai]

Summary

This PR adds 82 .describe() annotations to all Zod parameter schemas, enabling AI agents to better understand tool parameters and their usage.

Why This Matters

Currently, AI agents using this MCP server have no documentation for tool parameters. They must guess:

• What each parameter does
• What values are valid
• What formats to use (ISO codes, UUIDs, etc.)
• What the defaults are
• What recommended ranges to use

With .describe() annotations, all this information is included in the JSON Schema output via tools/list, enabling any MCP client to provide better parameter guidance.

Changes

Before (0 descriptions):

url: z.string().url(),
waitFor: z.number().optional(),
maxAge: z.number().optional(),

After (with descriptions):

url: z.string().url().describe("The URL to scrape content from. Must be a valid HTTP/HTTPS URL"),
waitFor: z.number().optional().describe("Milliseconds to wait before scraping. Useful for dynamic content..."),
maxAge: z.number().optional().describe("Maximum cache age in milliseconds. Use cached results if available..."),

Coverage

Tool	Parameters	Descriptions Added
firecrawl_scrape	15	✅ All
firecrawl_map	6	✅ All
firecrawl_search	8	✅ All
firecrawl_crawl	16	✅ All
firecrawl_check_crawl_status	1	✅ All
firecrawl_extract	6	✅ All
firecrawl_agent	3	✅ All
firecrawl_agent_status	1	✅ All
Total	56 top-level + 26 nested	82

Description Quality

Each description includes where applicable:

• Clear explanation of purpose
• Concrete examples (e.g., 'US', 'GB', 'DE')
• Format specifications (e.g., "ISO 3166-1 alpha-2")
• Default values
• Recommended ranges
• Caveats and warnings

Verification

# Count descriptions
grep -c '\.describe(' src/index.ts
# Output: 82

# Verify in JSON Schema output
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js | \
  jq '.result.tools[0].inputSchema.properties.url.description'
# Output: "The URL to scrape content from. Must be a valid HTTP/HTTPS URL"

Test plan

• TypeScript compiles without errors
• All 82 descriptions appear in tools/list JSON Schema output
• Nested schema descriptions (location, actions, formats, parsers) work correctly
• SAFE_MODE conditional schemas still work (actions/webhook excluded when enabled)

🤖 Generated with Claude Code