add_geo_audit_recommendation

add_geo_audit_recommendation adds a custom recommendation to a GEO Audit report, exactly like an owner can do by hand in the audit UI. It lets an agent enrich a report with its own recommendations programmatically. On a bulk campaign the recommendation lands on the shared template, so every target report gets it. Tenant-scoped write.

When to use

After reading the audit and its existing recommendations (get_geo_audit, list_geo_audit_recommendations), add the recommendations your workflow generated. The new recommendation appears in the audit report alongside the AI-generated ones.

Input

GEO Audits are workspace-scoped, so this tool takes no projectId. Address a report with auditId or bulkAuditId, never both. On a bulk campaign the change applies to the shared settings template every target report renders, so one call covers the whole batch. Passing a campaign target's auditId resolves to its campaign for the same reason: a target has no settings of its own. The response always echoes the resolved target as auditId / bulkAuditId (one of them null).

Response

Success

{
  "success": true,
  "auditId": "clx_audit_42",
  "reco": {
    "id": "cus_ab12cd34",
    "category": "content",
    "severity": "important",
    "title": "Publish a head-to-head comparison page",
    "description": "Cover the three competitors named most often by the LLMs."
  }
}

The returned reco.id is the handle to remove it later with remove_geo_audit_recommendation.

Errors

{ "success": false, "error": "target_required", "message": "Pass exactly one of auditId (a GEO audit) or bulkAuditId (a bulk campaign)." }
{ "success": false, "error": "audit_not_found", "message": "No GEO audit with this id exists in your workspace. ..." }
{ "success": false, "error": "bulk_audit_not_found", "message": "No bulk campaign with this id exists in your workspace. ..." }

Tips and patterns

• List first with list_geo_audit_recommendations to avoid duplicating an existing recommendation.
• Keep titles specific. The title is what readers scan; put the action in it (for example "Add FAQ schema to the pricing page").
• Custom recommendations are editable: remove them with remove_geo_audit_recommendation. There is no update call: remove, then add.
• On a campaign, one add serves N reports. Use bulkAuditId (or any target's auditId) when the point applies to the whole segment.

Related tools

• list_geo_audit_recommendations: read current recommendations first.
• remove_geo_audit_recommendation: remove a custom recommendation by id.