create_firmographic_audience

Create B2B company firmographic audiences for targeted advertising campaigns.
                Build audiences based on company attributes (industry, size, revenue) and contact-level criteria.

                ESTIMATE-ONLY MODE:
                Pass estimate_only=true to preview audience size (companies + contacts) WITHOUT creating the audience.
                In this mode the tool returns expectedNumberOfCompanies,
                expectedNumberOfContacts, and cappedContactCount. Default is false (audience is created).

                PREFERRED AUDIENCE TYPE:
                This is the DEFAULT and most commonly used audience type on the Metadata platform.
                When the user asks to create an audience without specifying a type, prefer this tool.
                Only suggest Bombora audiences if get_intent_topics returns available topics.
                Only suggest G2 audiences if G2 is confirmed as connected via get_integrations_status
                and the user specifically requests G2 targeting.

                ALSO KNOWN AS: company audience, target companies, B2B audience, business targeting, account-based audience, ABM list, company targeting

                KEYWORDS: company, companies, audience, target, targeting, B2B, business, firmographic, industry, size, employees, revenue, ABM, account-based, LinkedIn, Facebook

                WHEN TO USE:
                - Default choice when the user wants to create a B2B audience
                - Create targeted B2B audiences for LinkedIn, Facebook campaigns
                - Target companies by industry, size, revenue
                - Target contacts by seniority level and job function
                - Set geographic targeting and contact limits per company

                TARGETING OPTIONS:
                - Industries: Use industry IDs. Examples:
                  1=Defense & Space, 4=Computer Software, 6=Internet, 7=Semiconductors, 8=Telecommunications,
                  11=Management Consulting, 12=Biotechnology, 41=Banking, 42=Insurance, 43=Financial Services,
                  80=Marketing & Advertising, 96=Information Technology & Services, more values in detail in the input schema
                - Employees: "0 - 9", "10 - 49", "50 - 199", "200 - 499", "500 - 999", "1,000 - 4,999", "5,000 - 9,999", "10,000+"
                - Revenue: "$1M - $10M", "$10M - $50M", "$50M - $100M", "$100M - $200M", "$500M - $1B", "$1B+"

                CONTACTS CRITERIA:
Use the following parameters to filter and target specific contacts within accounts:

GEOGRAPHIC TARGETING:
- location_country_ids: Array of country IDs (e.g., [29] for Brazil, [229] for United States)
- location_state_ids: Array of state IDs (e.g., [5] for California, [32] for New York)

JOB TITLES:
- job_title_includes: Array of free text strings to include (e.g., ["Software Engineer", "Manager"])
- job_title_excludes: Array of free text strings to exclude (e.g., ["Senior", "Lead"])

JOB FUNCTIONS:
Valid job function IDs and their labels:
- 1: Marketing, 2: Sales, 3: Customer Service, 4: Finance, 5: Human Resources, 6: Public Relations
- 7: Media, 8: Design, 9: Engineering, 10: Operations, 11: Legal, 12: Education
- 13: Health, 14: Real Estate, 15: Accounting, 16: Administrative, 17: Business Development
- 18: Community and Social Services, 19: Consulting, 20: Entrepreneurship, 21: Information Technology
- 22: Military and Protective Services, 23: Product Management, 24: Program and Project Management
- 25: Purchasing, 26: Quality Assurance, 27: Research, 28: Trades

- job_function_include_ids: Array of job function IDs to include (e.g., [9] for Engineering)
- job_function_exclude_ids: Array of job function IDs to exclude

SENIORITY LEVELS:
Valid seniority IDs and their labels:
- 2: Manager, 3: Director, 4: VP, 5: CXO, 6: Unpaid, 7: Training
- 8: Senior, 9: Owner, 10: Entry, 11: Partner

- seniority_include_ids: Array of seniority level IDs to include (e.g., [10, 7] for Entry and Training)
- seniority_exclude_ids: Array of seniority level IDs to exclude

CONTACT LIMITS:
- contacts_per_company_limit: Maximum number of contacts to target per company (optional). Example: 20

USAGE NOTES:
- All ID fields (countries, states, job functions, seniorities) use numeric IDs from the platform
- Job titles are free text strings, not IDs
- Use include parameters to specify which criteria to target
- Use exclude parameters to filter out contacts matching specific criteria
- Combine multiple criteria for precise targeting (e.g., Senior Engineers in California)
- Criteria are combined with AND logic, so all conditions must be met

CONTACTS CRITERIA PARAMETERS(Usually after other initial audience parameters to be described next):
- location_country_ids: Array of country IDs (optional)
- location_state_ids: Array of state IDs (optional)
- job_title_includes: Array of job title keywords to include (optional)
- job_title_excludes: Array of job title keywords to exclude (optional)
- job_function_include_ids: Array of job function IDs (optional)
- job_function_exclude_ids: Array of job function IDs (optional)
- seniority_include_ids: Array of seniority level IDs (optional)
- seniority_exclude_ids: Array of seniority level IDs (optional)
- contacts_per_company_limit: Maximum contacts per company (optional)


                PARAMETERS:
                - name: Audience name (required) - **IMPORTANT: Name MUST NOT exceed 50 characters. This is a mandatory requirement.**
                - industries: Array of industry IDs (optional)
                - employees: Array of employee count ranges (optional)
                - revenue: Array of revenue ranges (optional)

                RETURNS:
                Audience details with ID, size estimation, and creation status.

                COMMON USE CASES:
                - Target software companies with 50-500 employees
                - Find companies in specific industries with revenue ranges
                - Build audiences with contact-level filtering (seniority, job function, location)
                - Combine firmographic and contact criteria for precise B2B targeting

                IMPORTANT NOTES:
                - **CRITICAL: Audience name MUST NOT exceed 50 characters - this is mandatory and will cause creation to fail if exceeded**
                - name is the only required parameter
                - All other parameters are optional for flexible audience creation
                - Contact criteria fields work the same as in G2 metadata dynamic audiences
                - Audience size depends on firmographic filters and applied contacts criteria