Agent Management Tools

All tools use gnosari_id (not agent_id) as the identifier parameter. They call core services directly — no HTTP proxy to the Gnosari API.

Errors propagate as MCP-level isError: true responses, not as success: false dicts.

gnosari_create

Create a new private agent with sensible defaults.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Parameters

Name	Type	Required	Description
`name`	string	Yes	Display name shown in chat and dashboard
`instructions`	string	Yes	System prompt defining the agent's behavior and goals
`description`	string	No	Agent purpose description for the dashboard

Returns

AgentSummaryWithHints:

Field	Type	Description
`agent`	`AgentSummaryRead`	Summary with `gnosari_id`, `name`, `access_level`, `model`
`hints`	`list[str]`	Maximum hints — bare agent needs full configuration

Example

python

result = gnosari_create(
    name="Product Support Bot",
    instructions="You help customers with product questions and troubleshooting."
)

gnosari_id = result.agent.gnosari_id
print(result.hints)
# ["Set instructions with gnosari_manage_instructions...",
#  "Make public with gnosari_manage_access...",
#  "Add knowledge with gnosari_manage_knowledge...", ...]

gnosari_get

Get a complete overview of an agent's configuration.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Parameters

Name	Type	Required	Default	Description
`gnosari_id`	integer	Yes	-	ID of the agent to retrieve
`include_instructions`	boolean	No	`false`	Include full instructions text (default false to reduce token cost)

Returns

GnosariOverview — organized into logical sections:

Section	Fields
Identity	`gnosari_id`, `name`, `description`, `model`, `temperature`, `reasoning_effort`
Instructions	`instructions_length`, `instructions_preview`, `instructions` (if requested)
Access	`access_level`, `uri`, `domain_name`, `domain_id`, `public_url`
Appearance	`greeting`, `empty_state_title`, `empty_state_description`, `suggested_prompts`, `theme_id`, `image_url`
Knowledge	`sources` (list of `KnowledgeSourceSummaryRead`)
Traits	`traits` (list of `TraitSummaryRead`)
Data Collection	`templates` (list of `_DataCollectionItem` with `id`, `name`, `collection_mode`)
Collection Summary	`collection` (`CollectionSummaryOut` \| `null`) — `record_count`, `new_count`, `last_capture` for this agent (`null` if no records collected)
Hints	`hints` (empty when fully configured)

Example

python

overview = gnosari_get(gnosari_id=123)

print(f"Agent: {overview.name}")
print(f"Access: {overview.access_level}")
print(f"Public URL: {overview.public_url}")
print(f"Knowledge sources: {len(overview.sources)}")
print(f"Instructions preview: {overview.instructions_preview}")

# Get full instructions
overview_full = gnosari_get(gnosari_id=123, include_instructions=True)
print(overview_full.instructions)

gnosari_update

Update an agent's identity and model settings. Only modifies provided fields.

For instructions, access, appearance, knowledge, traits, and data collection — use the dedicated tools.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Parameters

Name	Type	Required	Description
`gnosari_id`	integer	Yes	ID of the agent to update
`name`	string	No	New display name
`description`	string	No	New purpose description
`model`	string	No	LLM model (e.g. `gpt-4o`, `gpt-5-mini`, `claude-sonnet-4`)
`temperature`	float	No	Creativity 0.0–2.0
`reasoning_effort`	string	No	Depth: `low`, `medium`, `high` (Claude models only)

At least one field must be provided. If none are provided, raises ValueError.

Returns

AgentSummaryWithHints with hints reflecting current configuration state.

Example

python

# Change model and temperature
result = gnosari_update(
    gnosari_id=123,
    model="gpt-5",
    temperature=0.5
)
print(result.agent.model)  # "gpt-5"

gnosari_delete

Delete an agent and all its associated data. Two-phase: preview first, confirm second.

Annotations: readOnlyHint: false · destructiveHint: true · idempotentHint: true · openWorldHint: false

Parameters

Name	Type	Required	Default	Description
`gnosari_id`	integer	Yes	-	ID of the agent to delete
`confirmed`	boolean	No	`false`	Must be `true` to delete. When `false`, returns warning details

Returns

confirmed=false → DeleteConfirmationResponse: includes agent name, access level, warning message, and instruction for confirming
confirmed=true → DeletedResponse: {"gnosari_id": 123, "message": "Agent 123 permanently deleted."}

Example

python

# Phase 1: Preview
preview = gnosari_delete(gnosari_id=123)
print(preview.warning)
# "Deleting 'Support Bot' will permanently remove the agent,
#  its joina.chat link, collected data, knowledge, traits, and config."

# Phase 2: Confirm (after user approval)
result = gnosari_delete(gnosari_id=123, confirmed=True)
print(result.message)  # "Agent 123 permanently deleted."

gnosari_manage_instructions

Update an agent's system instructions.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Parameters

Name	Type	Required	Description
`gnosari_id`	integer	Yes	ID of the agent to update
`action`	string	Yes	`replace`, `append`, or `prepend`
`content`	string	Yes	Instruction text to apply

Action	Effect
`replace`	Overwrites all current instructions
`append`	Adds content to the end of existing instructions
`prepend`	Adds content to the beginning of existing instructions

Returns

InstructionsResult:

Field	Type	Description
`gnosari_id`	int	Agent ID
`instructions_length`	int	Character count after operation
`preview`	str	First 200 characters
`action_performed`	str	What was done
`hints`	list[str]	Contextual next steps

Example

python

# Replace all instructions
result = gnosari_manage_instructions(
    gnosari_id=123,
    action="replace",
    content="You are a helpful customer support agent for Acme Corp..."
)
print(f"Instructions: {result.instructions_length} chars")

# Add a rule at the end
gnosari_manage_instructions(
    gnosari_id=123,
    action="append",
    content="\n\nAlways end responses with: 'Is there anything else I can help you with?'"
)

gnosari_manage_access

Configure an agent's access level and public URL.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Parameters

Name	Type	Required	Description
`gnosari_id`	integer	Yes	ID of the agent to update
`access_level`	string	Yes	`PUBLIC`, `PRIVATE`, or `PASSWORD_PROTECTED`
`uri`	string	No	URL path for `joina.chat/{uri}`. Required for PUBLIC/PASSWORD_PROTECTED
`domain`	string	No	Domain name to publish on (resolved to domain_id)
`domain_id`	integer	No	Domain ID (takes precedence over `domain` if both provided)
`password`	string	No	Password for `PASSWORD_PROTECTED` access (min 8 chars)

Access Level	Who can access
`PUBLIC`	Anyone with the joina.chat link
`PASSWORD_PROTECTED`	Anyone with the link + password
`PRIVATE`	API/embed access only (no public URL)

Returns

AgentSummaryWithHints. The agent.public_url field is populated when access level is PUBLIC or PASSWORD_PROTECTED.

Examples

python

# Make agent public
result = gnosari_manage_access(
    gnosari_id=123,
    access_level="PUBLIC",
    uri="support-bot"
)
print(result.agent.public_url)  # "https://joina.chat/acme/support-bot"

# Password-protected
gnosari_manage_access(
    gnosari_id=123,
    access_level="PASSWORD_PROTECTED",
    uri="internal-bot",
    password="secret2024"
)

# Revert to private
gnosari_manage_access(gnosari_id=123, access_level="PRIVATE")

gnosari_manage_appearance

Configure an agent's visual appearance and welcome experience. This is the primary surface for theming a chat — the schema alone is enough to apply a complete visual identity.

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

At least one field must be provided.

The two config layers

Chat appearance resolves from two layers:

Layer	Where it lives	What it holds	Set via
1. Agent chat UI (CONTENT)	`Agent.configuration.chat_ui`	Per-agent greeting, empty-state, suggested prompts.	`greeting`, `empty_state_*`, `suggested_prompts`
2. Chat theme (VISUAL identity)	`chat_theme.configuration` (canonical v2)	Reusable branding — color preset + background pattern. Branding is theme-only — agents never override it per chat.	`style_preset`

Visual identity is chosen with ONE curated style_preset (see below). The preset resolves to a color preset + background pattern and is written to the agent's chat theme. Theme writes reuse the agent's existing theme in place (one row) — repeated calls never create duplicate theme rows.

Parameters

Name	Type	Required	Description
`gnosari_id`	integer	Yes	ID of the agent to update
`greeting`	string	No	First message shown when a user opens a new chat (layer 1)
`empty_state_title`	string	No	Large title text for the welcome screen (layer 1)
`empty_state_description`	string	No	Supporting text below the welcome title (layer 1)
`suggested_prompts`	list[SuggestedPromptInput]	No	Clickable prompt buttons (max 8). Replaces all existing (layer 1)
`style_preset`	string (enum)	No	ONE curated visual identity — color preset + background pattern (layer 2). One of the 12 values below
`image_url`	string	No	Agent avatar/logo URL (max 500 chars, publicly accessible)

SuggestedPromptInput format:

python

{"title": "Button label", "prompt": "Full prompt text sent on click"}

`style_preset`

A style_preset is a single curated combo that covers BOTH the color palette and the background pattern — pick one by the agent's purpose/brand. It is a type-locked enum: only the 12 values below are accepted, and there is no raw-hex or font input from this tool. Applying a preset writes (or updates in place) the agent's chat theme and echoes the applied id back in the result.

`style_preset`	Color	Pattern	Use it for
`plain`	sky	none	No pattern, clean sky accent. Corporate/formal, or let content lead.
`clean-dots`	sky	fine-dots	Minimal sky-blue, faint dots. SaaS, B2B, dashboards.
`ocean-waves`	ocean	waves	Calm blue, flowing waves. Wellness, travel, spa, relaxed brands.
`forest-topo`	forest	topography	Green, contour lines. Outdoors, sustainability, nature, eco.
`blueprint`	blue	blueprint	Technical blue grid. Engineering, dev tools, architecture.
`graph-paper`	indigo	graph-paper	Indigo grid. Education, finance, data, analytical tone.
`circuit`	teal	circuit	Teal circuit lines. Tech, hardware, AI, electronics.
`soft-bubbles`	rose	bubbles	Warm rose, soft bubbles. Friendly, lifestyle, community, care.
`sunset-glow`	sunset	organic-blobs	Vibrant sunset, organic blobs. Creative, marketing, bold consumer.
`emerald-grid`	emerald	subtle-grid	Fresh emerald, subtle grid. Health, growth, productivity.
`confetti`	fuchsia	confetti	Energetic fuchsia, confetti. Events, kids, playful/fun brands.
`mono-noise`	violet	noise	Editorial violet, subtle grain. Media, publishing, premium/minimal.

Returns

AppearanceResult:

Field	Type	Description
`gnosari_id`	int	Agent ID
`greeting`	str	Current greeting
`empty_state_title`	str	Current title
`empty_state_description`	str	Current description
`suggested_prompts_count`	int	Number of prompts configured
`chat_theme_id`	int \| null	Current theme ID (the DB row id; echoed so you can confirm the in-place reuse)
`style_preset`	str \| null	The `style_preset` id applied on this call (echoed back), or null if none
`image_url`	str	Current avatar URL
`note`	str	Advisory note (e.g. greeting hides the welcome screen)
`readiness`	Readiness	Configuration completeness with missing keys and next steps

Examples

Welcome content + a curated visual identity:

python

result = gnosari_manage_appearance(
    gnosari_id=123,
    greeting="Hi! How can I help you today?",
    empty_state_title="Acme Support",
    empty_state_description="Ask questions about our products and services.",
    suggested_prompts=[
        {"title": "What's included?", "prompt": "What's included in the Pro plan?"},
        {"title": "How do I get started?", "prompt": "Walk me through getting started"}
    ],
    style_preset="clean-dots",
    image_url="https://example.com/avatar.png"
)
print(f"Prompts configured: {result.suggested_prompts_count}")
print(f"Style preset applied: {result.style_preset}")

Change just the visual identity (reuses the agent's theme row in place):

python

result = gnosari_manage_appearance(
    gnosari_id=123,
    style_preset="ocean-waves",
)
print(f"Theme assigned: {result.chat_theme_id} — preset {result.style_preset}")

gnosari_health_check

Health check for monitoring server status.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

No parameters. No authentication required.

Returns

python

{
    "status": "healthy",
    "server": "gnosari-mcp",
    "version": "x.x.x",
    "api_url": "http://gnosari-api.localhost"
}

Example

python

health = gnosari_health_check()
print(health["status"])   # "healthy"
print(health["version"])  # "2.1.0"

Common Errors

Error	Cause	Solution
`AgentNotFoundError`	`gnosari_id` does not exist	Verify ID with `gnosari_search`
`AgentAccessDeniedError`	Agent belongs to a different account	Confirm the ID belongs to your account
`AgentValidationError`	URI already taken on the domain	Check with `gnosari_check_uri` first
`ValueError` (no update fields)	Called `gnosari_update` with no fields	Provide at least one field to update
`ValueError` (no appearance fields)	Called `gnosari_manage_appearance` with no fields	Provide at least one appearance field

Next Steps

Manage Resource Tools - Traits, knowledge, data collection
Discovery Tools - Search and URI check
Agent Creation Flow - Atomic decomposition walkthrough

Agent Management Tools ​

gnosari_create ​

Parameters ​

Returns ​

Example ​

gnosari_get ​

Parameters ​

Returns ​

Example ​

gnosari_update ​

Parameters ​

Returns ​

Example ​

gnosari_delete ​

Parameters ​

Returns ​

Example ​

gnosari_manage_instructions ​

Parameters ​

Returns ​

Example ​

gnosari_manage_access ​

Parameters ​

Returns ​

Examples ​

gnosari_manage_appearance ​

The two config layers ​

Parameters ​

style_preset ​

Returns ​

Examples ​

gnosari_health_check ​

Returns ​

Example ​

Common Errors ​

Next Steps ​

Agent Management Tools

gnosari_create

Parameters

Returns

Example

gnosari_get

Parameters

Returns

Example

gnosari_update

Parameters

Returns

Example

gnosari_delete

Parameters

Returns

Example

gnosari_manage_instructions

Parameters

Returns

Example

gnosari_manage_access

Parameters

Returns

Examples

gnosari_manage_appearance

The two config layers

Parameters

`style_preset`

Returns

Examples

gnosari_health_check

Returns

Example

Common Errors

Next Steps