# Mjhr Mjhr is a Saudi sales intelligence and company discovery platform that helps teams find, filter, save, and export ready-to-use company opportunities. ## Primary Machine-Readable Resources - Full LLM context: https://help.mjhr.ai/llms-full.txt - Well-known LLM context: https://help.mjhr.ai/.well-known/llms.txt - OpenAPI: https://help.mjhr.ai/openapi.json - MCP endpoint: https://help.mjhr.ai/mcp - API LLM context: https://help.mjhr.ai/api/llms.txt - API full context: https://help.mjhr.ai/api/llms-full.txt - Help and API LLM context: https://help.mjhr.ai/llms.txt - API service origin: https://api.mjhr.ai - Sitemap index: https://help.mjhr.ai/sitemap.xml - Page sitemap: https://help.mjhr.ai/pages/sitemap.xml ## API Endpoint Inventory | Method | Path | Operation | Purpose | | --- | --- | --- | --- | | GET | /v1/workspace | get_workspace | Get workspace metadata | | GET | /v1/countries | list_countries | List Search country references | | GET | /v1/cities | list_cities | List Search city references | | GET | /v1/cities/{cityId} | get_city | Get a Search city reference | | GET | /v1/cities/{cityId}/districts | list_city_districts | List city district references | | GET | /v1/categories | list_categories | List Search category references | | GET | /v1/searches | list_searches | List saved searches | | POST | /v1/searches | create_search | Submit a new saved search | | GET | /v1/searches/{searchId} | get_search | Get a saved search | | GET | /v1/searches/{searchId}/results | list_search_results | List saved search results | | GET | /v1/results/{searchId} | list_result_companies | List result companies | | GET | /v1/results/{searchId}/branches | list_result_branches | List result branches | | GET | /v1/results/{searchId}/{companyId} | list_company_result_branches | List one result company’s branches | | POST | /v1/results/{searchId}/folder | move_result_to_folder | Move a result set to a folder | | POST | /v1/results/{searchId}/archive | archive_result_set | Archive a result set | | GET | /v1/folders | list_folders | List search-history folders | | POST | /v1/folders | create_folder | Create a search-history folder | | POST | /v1/folders/{folderId}/archive | archive_folder | Archive a search-history folder | | GET | /v1/lists | list_branch_lists | List active Branch Lists | | POST | /v1/lists | create_branch_list | Create a Branch List | | GET | /v1/lists/{listId} | get_branch_list | Get Branch List metadata | | POST | /v1/lists/{listId}/rename | rename_branch_list | Rename a Branch List | | POST | /v1/lists/{listId}/archive | archive_branch_list | Archive a Branch List | | GET | /v1/lists/{listId}/members | list_branch_list_members | List Branch List members | | POST | /v1/lists/{listId}/members | add_branch_list_members | Add Branches to a List | | POST | /v1/lists/{listId}/members/remove | remove_branch_list_members | Remove Branches from a List | | POST | /v1/lists/{listId}/order | reorder_branch_list_members | Replace Branch List order | ## Help Navigation ### Start here - [Choose your help path](https://help.mjhr.ai/start-here) Start here when you want to know which Mjhr guide matches your job. ### Core workflows - [Search for companies](https://help.mjhr.ai/search-for-companies) Use prompts, filters, and result counts to create focused Search Results in Mjhr. - [Review saved results](https://help.mjhr.ai/review-results) Inspect saved companies, filter the result set, and open company details without changing the original search. - [Use saved searches](https://help.mjhr.ai/saved-searches) Return to Search Results you already created and understand what changes when you filter them. - [Curate Branches with Lists](https://help.mjhr.ai/lists) Keep revealed Branches together without rerunning or changing a Saved Search. - [Organize searches with folders](https://help.mjhr.ai/folders) Use folders to keep workspace search history clear by campaign, segment, or review need. ### Workspace management - [Manage account and workspace settings](https://help.mjhr.ai/account-and-workspace) Understand the settings areas that control profile, preferences, workspace details, and participants. - [Understand plans, usage, and billing](https://help.mjhr.ai/plans-usage-and-billing) Use subscription surfaces to understand the monthly allowance, plan options, and billing context. ### Developer resources - [Create a safe API key](https://help.mjhr.ai/api-authentication) Give another system only the Mjhr access it needs, then keep the token private. - [Use the public API](https://help.mjhr.ai/api-reference) Read workspace, saved search, result, and folder data from Mjhr. ### Agent resources - [Connect an AI agent](https://help.mjhr.ai/agent-integration) Help an agent discover Mjhr safely before it reads workspace data. # Mjhr API Use the Mjhr API to read workspace metadata, submit and read saved searches, read result companies and branches, move or archive result sets, create or archive folders, and curate reusable Branch Lists. ## Authentication Send a scoped API key in the Authorization header: `Authorization: Bearer `. ## Base URLs - API service: https://api.mjhr.ai/v1 - OpenAPI: https://help.mjhr.ai/openapi.json - MCP endpoint: https://help.mjhr.ai/mcp - Full API context: https://help.mjhr.ai/api/llms-full.txt ## Scopes - `workspaceRead` - `referenceRead` - `searchesRead` - `searchesWrite` - `resultsRead` - `resultsWrite` - `foldersRead` - `foldersWrite` - `listsRead` - `listsWrite` ## Endpoint Inventory | Method | Path | Operation | Purpose | | --- | --- | --- | --- | | GET | /v1/workspace | get_workspace | Get workspace metadata | | GET | /v1/countries | list_countries | List Search country references | | GET | /v1/cities | list_cities | List Search city references | | GET | /v1/cities/{cityId} | get_city | Get a Search city reference | | GET | /v1/cities/{cityId}/districts | list_city_districts | List city district references | | GET | /v1/categories | list_categories | List Search category references | | GET | /v1/searches | list_searches | List saved searches | | POST | /v1/searches | create_search | Submit a new saved search | | GET | /v1/searches/{searchId} | get_search | Get a saved search | | GET | /v1/searches/{searchId}/results | list_search_results | List saved search results | | GET | /v1/results/{searchId} | list_result_companies | List result companies | | GET | /v1/results/{searchId}/branches | list_result_branches | List result branches | | GET | /v1/results/{searchId}/{companyId} | list_company_result_branches | List one result company’s branches | | POST | /v1/results/{searchId}/folder | move_result_to_folder | Move a result set to a folder | | POST | /v1/results/{searchId}/archive | archive_result_set | Archive a result set | | GET | /v1/folders | list_folders | List search-history folders | | POST | /v1/folders | create_folder | Create a search-history folder | | POST | /v1/folders/{folderId}/archive | archive_folder | Archive a search-history folder | | GET | /v1/lists | list_branch_lists | List active Branch Lists | | POST | /v1/lists | create_branch_list | Create a Branch List | | GET | /v1/lists/{listId} | get_branch_list | Get Branch List metadata | | POST | /v1/lists/{listId}/rename | rename_branch_list | Rename a Branch List | | POST | /v1/lists/{listId}/archive | archive_branch_list | Archive a Branch List | | GET | /v1/lists/{listId}/members | list_branch_list_members | List Branch List members | | POST | /v1/lists/{listId}/members | add_branch_list_members | Add Branches to a List | | POST | /v1/lists/{listId}/members/remove | remove_branch_list_members | Remove Branches from a List | | POST | /v1/lists/{listId}/order | reorder_branch_list_members | Replace Branch List order | ## Result nesting - `GET /v1/results/{searchId}` returns companies. - `GET /v1/results/{searchId}/branches` returns all branches for those companies. - `GET /v1/results/{searchId}/{companyId}` returns branches for one company. - Result moves and result archives require `resultsWrite`; folder archives require `foldersWrite`. - Branch List reads require `listsRead`; lifecycle and atomic membership mutations require `listsWrite`. ## Full Help Documentation # Choose your help path Start here when you want to know which Mjhr guide matches your job. Canonical URL: https://help.mjhr.ai/start-here Machine-readable page: https://help.mjhr.ai/start-here/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## What Mjhr helps with Mjhr helps teams discover Saudi companies, keep useful Saved Searches, and curate Branches in Lists without rebuilding the same research from scratch. This help center is organized around the work people are trying to finish: find companies, keep history tidy, connect another tool, or give an agent the right context. ## Pick the path that matches your work - Start a new company search: Use the search guide when you are choosing prompts, filters, locations, categories, or result counts. - Find and revisit companies: Use Saved Searches when you want to reopen and narrow the exact result set you created. - Keep research organized: Use folders when several searches belong to the same campaign, segment, customer, or review cycle. - Connect another tool: Use the API key and API guides when a backend, reporting workflow, or internal tool needs to read workspace data. - Manage the workspace: Use the workspace and subscription guides when you need participants, settings, usage, plans, or billing context. - Support an AI agent: Use the agent guide when an assistant needs machine-readable context, OpenAPI details, or MCP tools before it helps with Mjhr data. ## Common questions - How do I create a better search? Start with search for companies. - Where did my previous search go? Start with saved searches. - How do I inspect companies inside Search Results? Start with review saved results. - How do I separate Saved Searches by campaign or account? Start with folders. - Where do profile, workspace, participants, usage, and billing live? Start with account and workspace settings. - How do I let another system read Mjhr data? Start with creating a safe API key. - Which resource should an agent read first? Start with the agent integration guide. ## Helpful entry points - [Search for companies](https://help.mjhr.ai/search-for-companies) Use prompts, filters, locations, categories, and result counts to create focused Search Results. - [Review saved results](https://help.mjhr.ai/review-results) Inspect saved companies, filter the visible result set, and open company details. - [Use saved searches](https://help.mjhr.ai/saved-searches) Understand what Mjhr saves and how to continue from a previous result set. - [Curate Branches with Lists](https://help.mjhr.ai/lists) Keep selected Branches together independently from Search History. - [Organize searches with folders](https://help.mjhr.ai/folders) Create simple folders so workspace history stays easy to scan. - [Create a safe API key](https://help.mjhr.ai/api-authentication) Choose access carefully before another system reads workspace data. - [Manage account and workspace settings](https://help.mjhr.ai/account-and-workspace) Find profile, preferences, workspace, participants, and active workspace guidance. - [Connect an AI agent](https://help.mjhr.ai/agent-integration) Give an agent the right context without exposing secrets or guessing endpoints. --- # Search for companies Use prompts, filters, and result counts to create focused Search Results in Mjhr. Canonical URL: https://help.mjhr.ai/search-for-companies Machine-readable page: https://help.mjhr.ai/search-for-companies/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## When to start a new search Start a new search when you need fresh Search Results rather than another view of an existing Saved Search. Mjhr supports both anonymous trial searches and registered workspace searches. Anonymous searches stay tied to the current browser; workspace searches are saved to the active workspace. - Use a clear prompt for the market, customer type, or company group you want to inspect. - Add filters when the location, category, or company size matters. - Choose a result count that matches how much review capacity you have. - Sign in when the search should become durable workspace history. ## Search inputs - Prompt: describe the companies you want in plain language. - Company type: narrow to small, medium, enterprise, government, or unknown company profiles. - Category: focus on a business activity or industry group. - Country and city: keep the list tied to the market you are reviewing. - Result count: control how many companies Mjhr should save for the search. ## Create a better search - Start broad enough to avoid missing useful companies: Describe the audience or market first, then use filters only for boundaries that truly matter. - Use filters as commitments: A selected category, country, city, or company type becomes part of the saved search context. - Review the first result set: Open the saved results and inspect whether the companies match the job you were trying to finish. - Create a new search when intent changes: If you want a different market, a broader result set, or different filters, create a new search instead of overloading the old one. ## Anonymous and workspace searches Anonymous searches are useful for a quick trial, but they depend on the same browser history. Registered searches are saved inside the active workspace and can be managed from search history. If a search matters to a team workflow, sign in before or after the trial flow so the history can be kept with the workspace. --- # Review saved results Inspect saved companies, filter the result set, and open company details without changing the original search. Canonical URL: https://help.mjhr.ai/review-results Machine-readable page: https://help.mjhr.ai/review-results/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## What a result page is A result page is a review surface for the companies saved under one search. It helps you inspect, narrow, sort, and open company details while staying inside that saved search. The page is not a new search engine query. Filtering and sorting help you understand the saved companies already captured by the search. ## Review controls - Display mode changes how companies are shown without changing the saved data. - Search saved companies filters the current saved set by text. - Facet filters narrow by company type, category, country, or city. - Sort controls reorder the visible saved results. - Pagination and page size control how much of the saved result set you inspect at once. - Active chips show the filters or sort currently applied and give you a quick way to remove them. ## Company details Opening a company shows the current profile details available for that saved result. The detail view can include company type, category, location, update date, website, phone, branch address, rating, review count, keywords, and public IDs. Use this panel to decide whether the company belongs in your next workflow before exporting, contacting, or sharing the result elsewhere. ## Good review habits - Start with the saved count: Confirm how many companies were saved before narrowing the list. - Use one filter at a time: Apply the strongest filter first so you can see which constraint changes the list. - Open details before acting: Check website, phone, branch, and location details before using a company for outreach or analysis. - Clear filters when comparing: Remove active chips before judging whether the original search matched your intent. --- # Use saved searches Return to Search Results you already created and understand what changes when you filter them. Canonical URL: https://help.mjhr.ai/saved-searches Machine-readable page: https://help.mjhr.ai/saved-searches/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## What a saved search keeps A Saved Search keeps the prompt, filters, and companies returned when the search was created. Reopening it returns to that saved result set. If you start without an account, Mjhr keeps that history in the same browser until you create an account and claim it. In a workspace, saved searches belong to that workspace so teammates can return to shared research. ## When to use a saved search - You found useful Search Results and want to continue from them later. - You want to compare the same result set after changing filters or sorting. - You need a stable result set for review, outreach planning, or an integration. - You want teammates to see the original search context, not just copied company names. ## Work with a saved search - Run a search: Describe the companies you want and add filters such as location, category, or company type. - Open it from history: Use the saved searches list or search history settings to return to the same saved search. - Narrow the list: Filtering or sorting a result page helps you inspect the saved companies. It does not expand the search into new companies. - Keep history clean: Rename searches when the original prompt is not clear, move them into folders, and archive searches you no longer need. ## Important boundaries - A saved result page shows the companies captured when the search was created. - Filters on a result page narrow the saved set; they do not run a new broader search. - Use the public search ID shown by the product or API. Internal database IDs are not part of the public contract. Note: If a list feels incomplete, create a new search with a broader prompt or fewer filters instead of expecting an old saved search to grow automatically. ## For integrations An integration can list saved searches, fetch one search by public ID, then read the companies and branches stored under that search. ### List saved searches ```bash curl -H "Authorization: Bearer $MJHR_API_KEY" \ "$MJHR_API_ORIGIN/v1/searches?limit=25" ``` ### List results for one search ```bash curl -H "Authorization: Bearer $MJHR_API_KEY" \ "$MJHR_API_ORIGIN/v1/searches/$SEARCH_ID/results?limit=100" ``` --- # Curate Branches with Lists Keep revealed Branches together without rerunning or changing a Saved Search. Canonical URL: https://help.mjhr.ai/lists Machine-readable page: https://help.mjhr.ai/lists/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## What a List keeps A List is a curated set of Branches you already revealed. Membership stays independent from the Saved Search that first revealed each Branch. Folders organize Saved Searches in Search History. Saved Searches preserve prompts, filters, and their original Search Results. Lists keep only the Branches you choose. ## Build a useful List - Open a Saved Search or Company: Select revealed Branches and choose an existing List, or create a List inline. - Review and refine membership: Open Lists from the Dashboard sidebar to filter, reorder, remove, copy, move, or export Branches. - Archive without deleting records: Archiving a List hides that collection only; it does not archive Branches, Companies, Folders, or Saved Searches. ## Availability and usage Lists are available to every registered Workspace during beta. Anonymous visitors must sign in before saving one. Adding an already revealed Branch to one or more Lists does not consume discovery allowance again. - [Read the Branch Lists API guide](https://help.mjhr.ai/https://docs.mjhr.ai/lists) Use List scopes and endpoints from a backend or agent workflow. --- # Organize searches with folders Use folders to keep workspace search history clear by campaign, segment, or review need. Canonical URL: https://help.mjhr.ai/folders Machine-readable page: https://help.mjhr.ai/folders/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## What folders are for Folders group saved searches inside a workspace. They are best for keeping related research together, such as a sales campaign, a customer request, or a market review. A search can sit inside a folder or remain unfiled. Keep folder names short and practical so teammates can understand them from the sidebar or history screen. ## A simple folder workflow - Create a folder: Open search history, enter a clear folder name, and create it before moving related searches. - Move searches into it: Use the folder selector on each saved search to file it under the right campaign or segment. - Rename as the work changes: Rename folders when a campaign name, account name, or review period changes. - Archive stale folders carefully: Use Archive only when the folder and searches are no longer needed in active history. ## Good folder labels - Use names people already say in the team, such as Q3 outreach or Riyadh clinics. - Prefer campaign, segment, account, or time period over vague names like Research. - Keep one idea per folder so searches do not become hard to scan later. - Leave one-off searches unfiled until they become part of a recurring workflow. ## Before archiving Archiving a folder removes it from active history along with the searches filed under it. Review the folder first, move any searches you still need, then archive it. Note: If you only need to clean up a single search, archive that search instead of archiving the full folder. ## For integrations An integration can list workspace folders and create folders for new workflows. ### Create a folder ```bash curl -X POST "$MJHR_API_ORIGIN/v1/folders" \ -H "Authorization: Bearer $MJHR_API_KEY" \ -H "Content-Type: application/json" \ --data '{"name":"Q3 prospecting"}' ``` --- # Manage account and workspace settings Understand the settings areas that control profile, preferences, workspace details, and participants. Canonical URL: https://help.mjhr.ai/account-and-workspace Machine-readable page: https://help.mjhr.ai/account-and-workspace/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## Settings map - Profile: update personal account details. - Preferences: adjust appearance and language preferences when available. - Workspace: review the active workspace details. - Participants: manage who belongs to the workspace. - Search history: manage saved searches and folders. - API keys: manage integration credentials. - Subscription: review usage, plans, and billing surfaces. ## Workspace context Workspace data is scoped. Searches, folders, participants, API keys, usage, and subscription information belong to the active workspace. If you have access to more than one workspace, use the workspace switcher before changing settings or reading saved history. ## Participants Use the participants area to review who has access to the workspace. Participant access affects who can see workspace search history and shared workspace resources. Note: Before changing participant access, confirm you are in the correct workspace. ## Good account habits - Sign in before important research so history is saved to a workspace. - Check the active workspace before creating searches, folders, or API keys. - Keep profile and preference settings current so the dashboard matches how you work. - Review participants before using workspace data in shared outreach or reporting workflows. --- # Understand plans, usage, and billing Use subscription surfaces to understand the monthly allowance, plan options, and billing context. Canonical URL: https://help.mjhr.ai/plans-usage-and-billing Machine-readable page: https://help.mjhr.ai/plans-usage-and-billing/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Users ## What usage means Usage is tied to saved company records across workspace searches. Search history and subscription usage help you understand how much of the workspace allowance is already used. - Saved searches show how many searches are active in the workspace. - Saved companies count the company records stored across those searches. - Folders count the active organization containers in search history. - Results per search limit how many companies a single search can save. ## Plans Use the plans surface to compare available workspace plans. The active plan controls the monthly allowance, results per search, seats, and custom requests per month. ## Billing Use the billing surface for subscription and payment context. Review billing before changing plans or making workspace-level decisions that affect the team. ## When to review usage - Before starting a large research cycle. - When a search returns fewer saved companies than expected. - Before inviting more participants to a workspace. - Before changing plan or billing settings. --- # Create a safe API key Give another system only the Mjhr access it needs, then keep the token private. Canonical URL: https://help.mjhr.ai/api-authentication Machine-readable page: https://help.mjhr.ai/api-authentication/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Developers ## Before you create a key Create API keys from the dashboard integration settings. Each key belongs to one workspace, so the key can only access data from that workspace. Copy the generated token when it is shown and store it in a server-side secret manager. Do not place it in browser code, client-side config, generated files, or chat logs. - Know which workspace the integration should read from. - Choose the smallest set of scopes needed for the job. - Name the key after the system or workflow that will use it. - Plan how you will rotate or revoke the key if access changes. ## Choose access - Workspace read: lets the integration confirm workspace identity, plan, and usage. - Searches read: lets it list saved searches and fetch one saved search. - Searches write: lets it submit new saved searches through the public API. - Results read: lets it read companies first, then branches through the nested results endpoints. - Results write: lets it move a result set to a folder or archive that result set. - Folders read: lets it list search-history folders. - Folders write: lets it create and archive folders, including archiving the searches inside a folder. Note: Read-only agents usually need workspace read, searches read, results read, and folders read. Add write scopes only when the user expects the tool to create searches, move/archive result sets, or create/archive folders. ## Send requests securely Send the token on each request with the Authorization header. ### Authorization header ```http Authorization: Bearer ``` ## Allowed origins API keys can be restricted by allowed origins. Server-side integrations usually do not need a browser origin. Browser-facing tools should call your backend first so the API key stays private. --- # Use the public API Read workspace, saved search, result, and folder data from Mjhr. Canonical URL: https://help.mjhr.ai/api-reference Machine-readable page: https://help.mjhr.ai/api-reference/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Developers ## What the API is for The public API is for tools that need to read Mjhr workspace data outside the dashboard. It covers workspace metadata, saved searches, saved search results, folders, and folder creation. Use the OpenAPI document as the source of truth for request parameters, response fields, and the current server URL. ## Start with these resources - [OpenAPI document](https://help.mjhr.ai/openapi.json) OpenAPI 3.1 contract generated from the API package. - [API LLM context](https://help.mjhr.ai/api/llms.txt) Concise agent-readable API guide. ## Current endpoints - GET /v1/workspace checks which workspace the key belongs to and returns plan usage. - GET /v1/searches lists saved searches visible to the key. - GET /v1/searches/{searchId} returns one saved search and its filters. - GET /v1/searches/{searchId}/results lists the companies and branches saved under that search. - GET /v1/folders lists search-history folders. - POST /v1/folders creates a search-history folder. ## Typical read flow - Confirm the workspace: Call /v1/workspace so the integration can show which workspace it is using before reading data. - List saved searches: Call /v1/searches to let the user choose the list they want to work with. - Fetch results: Call /v1/searches/{searchId}/results after the user or workflow chooses a saved search. - Use folders when helpful: Call /v1/folders to show organization context, or POST /v1/folders when the integration needs to create a new folder. Note: Use public IDs returned by the API in future calls. Do not construct IDs from database prefixes or internal table names. --- # Connect an AI agent Help an agent discover Mjhr safely before it reads workspace data. Canonical URL: https://help.mjhr.ai/agent-integration Machine-readable page: https://help.mjhr.ai/agent-integration/README.md Full help context: https://help.mjhr.ai/llms-full.txt Audience: Agents ## What an agent needs An agent should not guess how Mjhr works. It should read the product help, load the API contract, ask for a scoped credential when needed, and confirm the workspace or saved search before using data. The help package exposes human-readable pages and machine-readable resources so agents can start with the same source of truth as users and developers. ## Discovery order - Read llms.txt: Start at /llms.txt for the concise product map and links to deeper context. - Fetch OpenAPI: Use /openapi.json as the canonical HTTP contract before constructing requests. - Use MCP when available: Call /mcp when your runtime supports MCP tools. The tools mirror OpenAPI operations and delegate to the existing API. - Ask for missing credentials: Do not invent API keys. Ask the user to provide a scoped key or connect a secret store. - Confirm before using data: Show the workspace and saved search that will be queried before using results for analysis, outreach, or export workflows. ## MCP request shape The MCP endpoint speaks JSON-RPC over HTTP. Send Authorization on the MCP request; tool calls forward that header to the API service. ### List tools ```json { "jsonrpc": "2.0", "id": "tools", "method": "tools/list" } ``` ### Call a read-only tool ```json { "jsonrpc": "2.0", "id": "searches", "method": "tools/call", "params": { "name": "list_searches", "arguments": { "query": { "limit": 25 } } } } ``` ## Agent safety boundaries - Treat API keys as secrets and avoid writing them into generated files or logs. - Prefer read-only scopes unless the user explicitly asks the agent to create folders. - Explain which workspace and saved search will be queried before using results. - Use public IDs returned by the API, not internal database IDs. ---