Manage topics, queries, and personas

Manage the inputs to visibility scans: topics group related queries (the questions asked of AI platforms), and personas define the buyer perspectives each query is asked from. Queries live under topics; personas are added AI-generated from a prompt or specified manually.

When to use

Use these tools to shape what a scan measures before running it. Adjust topics and queries to cover the themes and questions that matter to the brand, and manage personas to test how AI platforms respond to different buyer types. New or edited items are automatically included in the next visibility scan; disabling (isActive: false) keeps an item for reference without running it, while deletes are irreversible. Get your syntheticId from get_account first. All writes here are blocked for accounts in read-only mode.

Typical sequence

1. list_visibility_topics — review current topics and their queries, and find topic/query IDs.
2. add_visibility_topic — add a topic (with optional queries) to cover a new theme.
3. update_visibility_topic / update_visibility_query — refine names, descriptions, reach levels, or active state.
4. delete_visibility_topic / delete_visibility_query — permanently remove what you no longer want scanned.
5. list_visibility_personas → add_visibility_persona → update_visibility_persona / delete_visibility_persona — manage the buyer perspectives scans run from.

Tools

list_visibility_topics

List all visibility topics and their queries for a brand. Topics group related search queries used in visibility scans. Use it to find topic and query IDs for the update/delete tools.

Authentication: Required. Deprecated alias list_topics is still accepted; list_visibility_topics is the canonical name.

Key response fields:

add_visibility_topic

Add a new visibility topic with optional queries. Topics group related search queries; each query has a reach level indicating how closely it relates to the brand. New topics and queries are automatically included in the next visibility scan.

Authentication: Required. A read-only account can't do this (it's a write). Deprecated alias add_topic is still accepted; add_visibility_topic is the canonical name.

update_visibility_topic

Rename or edit an existing topic, or toggle whether it is included in scans. Use it to fix typos, clarify a name, update a description, or temporarily disable a topic without deleting it. At least one of name, description, or isActive must be provided.

Authentication: Required. A read-only account can't do this (it's a write). Deprecated alias update_topic is still accepted; update_visibility_topic is the canonical name.

delete_visibility_topic

Permanently delete a topic and all of its queries. This is irreversible — historical scan data referencing the topic by name is preserved, but the topic and its queries won't appear in future scans. To keep a topic for reference, use update_visibility_topic with isActive: false instead.

Authentication: Required. Anyone with access to the agent — including shared team members — can delete a topic. A topic that doesn't exist (or belongs to another agent) returns a not-found error. Deprecated alias delete_topic is still accepted; delete_visibility_topic is the canonical name.

Returns deletedTopic with the removed topic's id and name.

update_visibility_query

Edit the text or reach level of an existing query, or toggle whether it runs in future scans. Queries live under a topic; find query IDs with list_visibility_topics. At least one of query, reachLevel, or isActive must be provided.

Authentication: Required. A read-only account can't do this (it's a write). Deprecated alias update_query is still accepted; update_visibility_query is the canonical name.

delete_visibility_query

Permanently delete a query. This is irreversible — the query won't appear in future scans. To keep it for reference, use update_visibility_query with isActive: false instead.

Authentication: Required. Anyone with access to the agent — including shared team members — can delete a query. A query that doesn't exist (or belongs to another agent) returns a not-found error. Deprecated alias delete_query is still accepted; delete_visibility_query is the canonical name.

Returns deletedQuery with the removed query's id and text.

list_visibility_personas

List all buyer personas for a brand. Personas represent different buyer types (e.g., "Technical Startup Founder", "Enterprise CMO"); each gets different AI responses because it carries different context and intent. Use it to find persona IDs for the update/delete tools.

Authentication: Required. Deprecated alias list_personas is still accepted; list_visibility_personas is the canonical name.

Key response fields:

add_visibility_persona

Add a buyer persona for visibility scans, in one of two modes. New personas are used in the next scan to test how AI platforms respond from that buyer's perspective.

1. Recommended — AI-generated: provide a prompt describing the buyer type. Pendium expands it into a full persona with demographics, goals, pain points, and system context.
2. Manual: provide structured fields (name, and optionally role, goals, painPoints) directly.

In AI-generated mode, whether a persona carries a geographic location (in its name, demographics, and system context) is judged from the brand's stated geographic focus and what it does. A genuinely local business — a physical premises or specific service area, like a restaurant, plumber, dentist, or contractor — gets its city or region woven in. An online, national, or SaaS brand (or one whose focus is a broad market like "US" or "Global") stays location-free, so scans aren't skewed by an assumed "near me" context.

Authentication: Required. A read-only account can't do this (it's a write). Deprecated alias add_persona is still accepted; add_visibility_persona is the canonical name.

AI-generated mode produces richer personas with demographics, system context, and more detailed goals/pain points. Use manual mode when you have a specific persona definition to preserve exactly.

update_visibility_persona

Edit an existing persona's name, role, goals, or pain points, or toggle whether it is used in scans. Use it to fix typos, sharpen role descriptions, or temporarily disable a persona without deleting it. At least one of name, role, goals, painPoints, or isActive must be provided.

Authentication: Required. A read-only account can't do this (it's a write). Deprecated alias update_persona is still accepted; update_visibility_persona is the canonical name.

delete_visibility_persona

Permanently delete a buyer persona. This is irreversible — the persona won't be used in future scans. To keep it for reference, use update_visibility_persona with isActive: false instead. Synchronous: the persona is removed the moment the call returns. Historical scan data that referenced the persona by name is preserved. The delete is scoped to syntheticId, so a personaId from another agent (or one that doesn't exist) returns a not-found result. Anyone with access to the agent — including shared team members — can delete a persona.

Authentication: Required. Deprecated alias delete_persona is still accepted; delete_visibility_persona is the canonical name.

Returns deletedPersona with the removed persona's id and name.