gaql_help

Instructions

Implementation Reference

• src/tools/gaqlHelp.ts:51-122 (handler)

  The primary handler function for the gaql_help tool. It provides GAQL documentation either for a specific topic from local markdown files or a default overview including quick tips, API version info, and links to official docs.

  export async function gaqlHelp(input: GaqlHelpInput = {}): Promise<string> {
    const sections: string[] = [];
    const version = getApiVersion();
    
    // If specific topic requested, return just that topic
    if (input.topic) {
      const topicContent = await readSpecificTopic(input.topic);
      if (topicContent) {
        sections.push(`# GAQL Help: ${input.topic.replace('-', ' ').toUpperCase()}`);
        sections.push(`**API Version**: ${version}\n`);
        sections.push(topicContent);
        
        // Add relevant official documentation link
        const officialUrl = OFFICIAL_URLS[input.topic.replace('-', '_') as keyof typeof OFFICIAL_URLS];
        if (officialUrl) {
          sections.push(`\n**Official Documentation**: ${officialUrl}`);
        }
        sections.push(`\n**Field References**: ${getFieldReferenceUrls().join(', ')}`);
        
        return sections.join('\n');
      } else {
        return `Topic "${input.topic}" not found. Available topics: ${AVAILABLE_TOPICS.join(', ')}`;
      }
    }
    
    // Default: Show overview with available topics
    sections.push('# Google Ads Query Language (GAQL) Help');
    
    // Show available topics
    sections.push(`
  ## Available Topics
  Use the topic parameter to get specific documentation:
  ${AVAILABLE_TOPICS.map(topic => `- **${topic}**: ${topic.replace('-', ' ')} documentation`).join('\n')}
  
  Example: Use topic="overview" for basic GAQL concepts`);
  
    // Quick Tips
    sections.push(`
  ## Quick Tips
  - FROM uses a RESOURCE (use list_resources tool to discover available resources)
  - SELECT fields must be selectable for the chosen FROM resource  
  - WHERE supports =, !=, <, >, >=, <=, LIKE, IN, DURING (for date ranges)
  - Date ranges: DURING LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, etc.
  - ORDER BY field [ASC|DESC], LIMIT n for sorting and limiting results
  - Case sensitivity: field names are case-insensitive; string values are case-sensitive
  - Cost fields are in micros - divide by 1,000,000 for actual currency amounts
  - Use customer.currency_code to interpret cost_micros correctly`);
  
    // API Version Info
    sections.push(`
  ## Current API Version: ${version}
  The MCP server is configured to use API version ${version}.
  Set GOOGLE_ADS_API_VERSION environment variable to use a different version.`);
  
    // Official Documentation Links
    sections.push(`
  ## Official Documentation
  ${Object.entries(OFFICIAL_URLS).map(([topic, url]) => `- ${topic.replace('_', ' ')}: ${url}`).join('\n')}
  
  ## Field References  
  ${getFieldReferenceUrls().join('\n')}`);
  
    // Footer
    sections.push(`
  ## Need More Help?
  - Use topic parameter to get detailed documentation on specific areas
  - Use the "list_resources" tool to discover available resources and their fields
  - Use the "execute_gaql_query" tool to test your queries
  - Check field compatibility in the official API reference above`);
  
    return sections.join('\n');
  }

• src/server-tools.ts:721-746 (registration)

  The registration of the 'gaql_help' tool using addTool(server, name, description, schema, handler), where the handler wraps and calls the gaqlHelp function with logging.

    server,
    "gaql_help",
    "Get GAQL help with local documentation and official Google Ads API links. Use topic for specific areas or search for keywords.",
    GaqlHelpZ,
    async (input: any) => {
      const startTs = Date.now();
      try {
        const text = await gaqlHelp({
          topic: input?.topic,
          search: input?.search,
        });
        const out = { content: [{ type: 'text', text }] };
        logEvent('gaql_help', startTs, { requestId: input?.request_id });
        return out;
      } catch (e: any) {
        const lines = [
          `Error fetching GAQL help: ${e?.message || String(e)}`,
          'Hint: set quick_tips=true to avoid network usage.',
        ];
        const out = { content: [{ type: 'text', text: lines.join('\n') }] };
        logEvent('gaql_help', startTs, { requestId: input?.request_id, error: { code: 'ERR_HELP', message: String(e?.message || e) } });
        return out;
      }
    }
  );

• src/schemas.ts:69-73 (schema)

  Zod schema (GaqlHelpZ) defining the input parameters for the gaql_help tool: optional topic (enum of GAQL topics) and search string.

  export const GaqlHelpZ = z.object({
    topic: z.enum(['overview', 'grammar', 'structure', 'date-ranges', 'case-sensitivity', 'ordering-limiting', 'cookbook', 'field-reference']).optional().describe('specific GAQL topic to retrieve'),
    search: z.string().optional().describe('search term for help content'),
  });
  export const GaqlHelpSchema: JsonSchema = zodToJsonSchema(GaqlHelpZ, 'GaqlHelp') as unknown as JsonSchema;