Discovery and Listing Tools

gnosari_search

Unified search across all Gnosari entity types with optional text query and structured filters.

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

Parameters

Name	Type	Required	Default	Description
query	string	No	-	Text search query. null returns all results using structured filters only
entity	string	No	"agents"	agents, traits, templates, knowledge, or all
access_level	string	No	-	Filter agents by: PUBLIC, PRIVATE, PASSWORD_PROTECTED. Ignored for non-agent entities
domain	string	No	-	Filter agents by domain name (e.g. "joina.chat"). Ignored for non-agent entities
sort_by	string	No	"updated_at"	updated_at, created_at, or name
sort_order	string	No	"desc"	asc or desc
limit	integer	No	20	Maximum results per entity type
skip	integer	No	0	Pagination offset

Returns

• Single entity (entity != "all") → SearchResult:

  • results: list[dict] — matching entities
  • total: int — total count
  • search_mode: str — search backend used: "opensearch_hybrid" or "sql_fallback"

• All entities (entity="all") → SearchAllResult:

  • agents: list[dict]
  • traits: list[dict]
  • templates: list[dict]
  • knowledge: list[dict]
  • total: int — count across all types
  • search_mode: str — search backend used: "opensearch_hybrid" or "sql_fallback"

The search_mode field indicates which backend produced the results. When OpenSearch is available and healthy, semantic hybrid search is used ("opensearch_hybrid"). When OpenSearch is unavailable or the query fails, the system transparently falls back to SQL ILIKE-based search ("sql_fallback").

Agent result dicts include a collection key with the lite shape {"record_count": int, "new_count": int}, or null if the agent has no collected records. last_capture is omitted at search time to keep response sizes small — use gnosari_get when the full collection summary (including last_capture) is needed.

::warning Eventual consistency: Results may take 1-2 seconds to reflect recent mutations (creates, updates, deletes). The search index is updated asynchronously via the outbox worker. On first deploy, run reindex_entities.py to populate the OpenSearch index with existing data. ::

Examples

Find agents by concept (semantic search):

results = gnosari_search(query="customer help desk", entity="agents")
print(f"Search mode: {results.search_mode}")
for agent in results.results:
    print(f"{agent['name']} (ID: {agent['id']}, {agent['access_level']})")
# Search mode: opensearch_hybrid
# Support Bot (ID: 123, PUBLIC)
# Enterprise Support (ID: 456, PRIVATE)

List all public agents:

results = gnosari_search(entity="agents", access_level="PUBLIC")
print(f"Public agents: {results.total}")

Search across everything:

results = gnosari_search(query="leads", entity="all")
print(f"Agents: {len(results.agents)}, Templates: {len(results.templates)}")
print(f"Search mode: {results.search_mode}")

Check search backend status:

results = gnosari_search(query="test", entity="agents")
if results.search_mode == "sql_fallback":
    print("OpenSearch unavailable -- using SQL fallback (exact match only)")

---

gnosari_check_uri

Check whether a URI is available for publishing an agent.

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

Parameters

Name	Type	Required	Description
uri	string	Yes	URI slug to check (e.g. "my-agent")
domain	string	No	Domain name to check on. Defaults to account's default domain

Returns

UriCheckResult:

Field	Type	Description
available	bool	Whether the URI is free to use
current_gnosari_id	int	ID of the agent using this URI (if taken)
current_gnosari_name	str	Name of the agent using this URI (if taken)
hints	list[str]	Suggestions for alternatives if taken

Example

check = gnosari_check_uri(uri="support-bot")
if check.available:
    gnosari_manage_access(gnosari_id=123, access_level="PUBLIC", uri="support-bot")
else:
    print(f"Taken by agent {check.current_gnosari_id}: {check.current_gnosari_name}")
    print(check.hints)
    # ["URI 'support-bot' is taken. Try variations like 'support-bot-2' or 'support-bot-bot'."]

---

Manage Tools — List Action

Each manage tool supports action="list" for read-only discovery:

gnosari_manage_traits(action="list")

result = gnosari_manage_traits(action="list")
# Returns PaginatedTraitsResponse
for trait in result.data:
    print(f"{trait.name} (ID: {trait.id}, weight: {trait.weight}, is_default: {trait.is_default})")
# Empathetic (ID: 42, weight: 2.0, is_default: True)
# Professional (ID: 17, weight: 1.0, is_default: False)

# Filter by search
result = gnosari_manage_traits(action="list", search="professional")

# Check which traits are auto-assigned to new agents
defaults = [t for t in result.data if t.is_default]

Each TraitRead item in result.data includes is_default: bool — True when the trait is automatically assigned to every interactively created new agent in the account.

gnosari_manage_knowledge(action="list")

result = gnosari_manage_knowledge(action="list")
# Returns PaginatedKnowledgeSourcesResponse
for source in result.data:
    print(f"{source.name}: {source.status} ({source.document_count} docs)")

# Filter by loading status
result = gnosari_manage_knowledge(action="list", status="failed")

gnosari_manage_data_collection(action="list")

result = gnosari_manage_data_collection(action="list")
# Returns PaginatedEntityTypesResponse
for template in result.data:
    print(f"{template.name} (system={template.is_template})")

# Exclude system templates
result = gnosari_manage_data_collection(action="list", include_system=False)

---

Tool Comparison

Tool	Purpose	readOnly	Auth
gnosari_search	Text search + filter across entities	Yes	Yes
gnosari_check_uri	URI availability check	Yes	Yes
gnosari_manage_traits(action="list")	List traits — each item includes is_default: bool	Yes	Yes
gnosari_manage_knowledge(action="list")	List knowledge sources	Yes	Yes
gnosari_manage_data_collection(action="list")	List data templates	Yes	Yes
gnosari_collected_data(action="list")	View collected records	Yes	Yes
gnosari_collected_data(action="stats")	Collection statistics	Yes	Yes
gnosari_health	Server status	Yes	No

---

Next Steps

• Agent Management Tools - CRUD and configuration tools
• API Overview - Tool relationships and patterns