> ## Documentation Index
> Fetch the complete documentation index at: https://docs.civicmarketplace.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools and Permissions
> What the CivicMarketplace AI Connector can do, and which permissions each workflow requires
The CivicMarketplace AI Connector exposes MCP tools for marketplace and approved public-source search, contract document reading, agency quote workflows, supplier dashboard workflows, inbox messaging, supplier creation, and admin maintenance.
Every tool is scoped to the signed-in CivicMarketplace user. Your assistant can only use tools allowed by your account type, organization access, and the OAuth permissions you approved.
Ask your assistant: *"Using CivicMarketplace, get my current user context."* The connector will
return the high-level actions available to your session.
## Permission model
| Permission | Enables |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| `contracts:read` | Search, count, and read contract details and supported public contract documents. |
| `suppliers:read` | Search, count, and read supplier profiles. |
| `suppliers:write` | Create suppliers. Supplier creation is limited to CivicMarketplace internal admin users. |
| `quote-requests:read` | Read agency quick quote and cooperative quote request status. |
| `quote-requests:write` | Create, archive, unarchive, cancel, reassign agency quote requests, or respond to supplier quote requests. |
| `inbox:read` | Read agency or supplier inbox conversation summaries and messages. |
| `inbox:write` | Send inbox replies and mark conversations read. |
| `team:read` | Read agency handoff colleagues or supplier team members/invites. |
| `team:write` | Manage supplier teammates when the signed-in supplier user is allowed to do so. |
| `supplier-profile:read` | Read the signed-in supplier's dashboard profile, addresses, keywords, certifications, and capacity. |
| `supplier-profile:write` | Update the signed-in supplier's dashboard profile, addresses, keywords, certifications, and capacity. |
| `supplier-media:read` | Read supplier dashboard catalogs, website links, and videos. |
| `supplier-media:write` | Manage supplier dashboard catalogs, website links, and videos. |
| `supplier-references:read` | Read supplier references and reference request status. |
| `supplier-references:write` | Send supplier reference requests. |
| `supplier-solicitations:read` | Read solicitations available to the signed-in supplier. |
| `supplier-solicitations:write` | Register intent to bid and ask solicitation questions. |
| `supplier-analytics:read` | Read supplier dashboard analytics and profile completeness. |
| `admin:read` | Use admin search and detail tools for suppliers, agencies, cooperatives, and contracts. |
| `admin:write` | Create and update admin records, status, and relationships. |
## Context
| Tool | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `get_current_user_context` | Shows authentication mode, identity claims, partner/agency/supplier IDs, granted scopes, and available MCP actions. |
## Marketplace read tools
| Tool | What it does |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `search_contracts` | Searches contracts by keyword, cooperative, supplier, service category, or update time. |
| `get_contract` | Returns full contract details, suppliers, lead entity, cooperative, dates, value bracket, NIGP codes, and document metadata. |
| `read_contract_document` | Reads extracted text chunks from supported contract documents: PDF, XLSX, CSV, and plain text. |
| `count_contracts` | Returns only the number of contracts matching a filter. |
| `search_suppliers` | Searches suppliers by keyword, state, certification, service category, or update time. |
| `get_supplier` | Returns full supplier profile details, contact info, certifications, served states, and source link. |
| `count_suppliers` | Returns only the number of suppliers matching a filter. |
## External public-source search
| Tool | What it does |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_external_contracts` | Searches 101 approved public procurement sources after a keyword search finds no CivicMarketplace contracts, or when you explicitly request it. |
| `read_external_contract_document` | Reads paginated text from a PDF, HTML page, or plain-text URL returned by external search, with physical page markers for PDFs. |
These read-only tools are available to every signed-in connector user and do not require an additional OAuth permission. External document reading is restricted to the configured public-procurement source inventory and applies download, redirect, file-size, and network-address safeguards. Extracted PDFs include one-based physical page markers so the assistant can cite the page supporting each claim. Results and extracted text are external public evidence, not imported or verified CivicMarketplace records. Your assistant should preserve that distinction when presenting them.
## Reference data
| Tool | What it does |
| --------------------- | ---------------------------------------------------------------------------------- |
| `list_lead_entities` | Lists lead entities that own contracts. |
| `list_coops` | Lists purchasing cooperatives available to the caller. |
| `list_city_services` | Lists service categories used by contracts and suppliers. |
| `search_nigp_codes` | Searches NIGP categories by plain-language purchasing need or class number. |
| `list_certifications` | Lists SBE/diversity and technical certifications available for supplier filtering. |
## Supplier creation
| Tool | What it does |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `create_supplier` | Creates one supplier profile, including metadata, certifications, categories, regions, NIGP codes, domains, and whitelisted emails. |
| `bulk_create_suppliers` | Creates suppliers from CSV text after validating every row. If any row is invalid, no suppliers are created. |
Supplier creation is metadata-only. It does not upload binary logo, catalog, insurance, or W-9
files; pass existing S3 keys where supported.
## Agency quote requests
| Tool | What it does |
| ---------------------------------- | --------------------------------------------------------------------------------------------------- |
| `create_quick_quote_request` | Creates a quick quote request for the authenticated agency and sends normal supplier notifications. |
| `bulk_create_quick_quote_requests` | Creates quick quote requests from CSV text after all rows validate. |
| `create_coop_request` | Creates a direct cooperative contract quote request for selected suppliers on a contract. |
| `bulk_create_coop_requests` | Creates cooperative quote requests from CSV text after all rows validate. |
| `list_quick_quote_requests` | Lists the authenticated agency's quick quote requests. |
| `list_coop_quote_requests` | Lists the authenticated agency's cooperative quote requests. |
| `get_quick_quote_request` | Reads one quick quote request with owner, status, suppliers, and response counts. |
| `get_coop_quote_request` | Reads one cooperative quote request with owner, status, suppliers, and response counts. |
| `get_quote_request_status_summary` | Summarizes quick and cooperative quote request statuses. |
| `change_quick_quote_owner` | Changes ownership for one quick quote request when the caller has permission. |
| `change_coop_quote_owner` | Changes ownership for one cooperative quote request when the caller has permission. |
| `archive_quick_quote_requests` | Archives selected quick quote requests. |
| `unarchive_quick_quote_requests` | Restores selected quick quote requests. |
| `archive_coop_quote_requests` | Archives selected cooperative quote requests. |
| `unarchive_coop_quote_requests` | Restores selected cooperative quote requests. |
| `cancel_quick_quote_request` | Cancels one waiting quick quote request by archiving it. |
| `cancel_coop_quote_request` | Cancels one waiting cooperative quote request by archiving it. |
## Agency inbox
| Tool | What it does |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| `get_inbox_unread_count` | Returns the authenticated user's unread conversation count. |
| `list_inbox_conversations` | Lists agency or supplier inbox conversations, optionally unread only. |
| `get_inbox_messages` | Reads messages in one inbox conversation. |
| `send_inbox_message` | Sends a reply in one inbox conversation. Attachments must reference existing S3 metadata. |
| `mark_inbox_conversation_read` | Advances the read cursor for one inbox conversation. |
## Supplier quote requests
These tools are for signed-in supplier users. They only show quote requests sent to the authenticated supplier account.
| Tool | What it does |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `list_supplier_quick_quote_requests` | Lists quick quote requests sent to the authenticated supplier. |
| `list_supplier_coop_quote_requests` | Lists cooperative quote requests sent to the authenticated supplier. |
| `get_supplier_quick_quote_request` | Reads one supplier-side quick quote request with agency, deadline, status, and response details. |
| `get_supplier_coop_quote_request` | Reads one supplier-side cooperative quote request with contract, agency, deadline, and status. |
| `get_supplier_quote_request_status_summary` | Summarizes supplier-facing quote statuses such as new, replied, awarded, declined, and expired. |
| `submit_supplier_quick_quote` | Submits a supplier response to one quick quote request. Attachments must use existing S3 metadata. |
| `submit_supplier_coop_quote` | Submits a supplier response to one cooperative quote request. |
| `decline_supplier_quick_quote` | Declines one quick quote request with a reason. |
| `decline_supplier_coop_quote` | Declines one cooperative quote request with a reason. |
## Supplier dashboard profile
These tools operate on the signed-in supplier's own dashboard profile. They never accept a `supplier_id`.
| Tool | What it does |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `get_my_supplier_profile` | Reads the supplier dashboard profile, including services, certifications, addresses, capacity, media, and references. |
| `update_my_supplier_profile` | Updates top-level profile fields such as company name, intro, website, contact info, and availability status. |
| `list_supplier_profile_options` | Lists lookup options for profile updates: states, keywords, certifications, and internal NIGP option IDs. |
| `set_supplier_states_served` | Replaces the full set of states served. |
| `set_supplier_services_certifications` | Replaces supplier keywords and/or certifications. Use add/remove tools for normal incremental changes. |
| `add_supplier_keywords` | Adds dashboard keywords/categories without removing existing keywords. |
| `remove_supplier_keywords` | Removes dashboard keywords/categories without changing other keywords. |
| `add_supplier_certifications` | Adds certifications without removing existing certifications. |
| `remove_supplier_certifications` | Removes certifications without changing other certifications. |
| `list_supplier_addresses` | Lists supplier dashboard addresses. |
| `add_supplier_address` | Adds an address to the supplier profile. |
| `update_supplier_address` | Updates one address owned by the supplier. |
| `delete_supplier_address` | Deletes one supplier address. |
| `set_supplier_primary_address` | Marks one supplier address as primary. |
| `list_supplier_capacity` | Lists capacity/NIGP rows currently attached to the supplier profile. |
| `set_supplier_capacity` | Replaces the full supplier capacity list. Use add/remove tools for normal incremental NIGP changes. |
| `add_supplier_capacity_nigp_codes` | Adds internal NIGP capacity codes without removing existing capacity rows. |
| `remove_supplier_capacity_nigp_codes` | Removes internal NIGP capacity codes without changing other capacity rows. |
For supplier dashboard keywords, the API field is `city_service_ids`. For capacity, use internal
`nigp_code_id` values returned by `list_supplier_profile_options` with `kind='nigp_codes'`, not
NIGP class numbers like 204 or 208.
## Supplier media
| Tool | What it does |
| ------------------------- | ------------------------------------------------------------------------------ |
| `list_supplier_catalogs` | Lists supplier dashboard catalog files. |
| `add_supplier_catalog` | Adds existing S3 catalog metadata. The connector does not upload binary files. |
| `delete_supplier_catalog` | Deletes one supplier catalog record. |
| `list_supplier_links` | Lists supplier dashboard website links. |
| `upsert_supplier_link` | Adds or updates a supplier dashboard link. |
| `delete_supplier_link` | Deletes one supplier dashboard link. |
| `list_supplier_videos` | Lists supplier dashboard videos. |
| `add_supplier_video` | Adds a supplier dashboard video entry. |
| `delete_supplier_video` | Deletes one supplier dashboard video entry. |
## Supplier references
| Tool | What it does |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- |
| `list_supplier_references` | Lists all references owned by the authenticated supplier. |
| `get_supplier_reference` | Reads full details for one supplier reference. |
| `list_supplier_reference_requests` | Lists reference requests sent by the authenticated supplier. Verification tokens are not returned. |
| `send_supplier_reference_request` | Sends a supplier reference request to one email address. |
## Supplier solicitations
| Tool | What it does |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| `list_supplier_solicitations` | Lists solicitations available to the authenticated supplier. |
| `get_supplier_solicitation` | Reads one solicitation, including documents, requested items, and bid status. |
| `register_supplier_solicitation_intent` | Registers intent to bid on one solicitation. |
| `ask_supplier_solicitation_question` | Asks a question on one solicitation as the authenticated supplier. |
## Supplier team and analytics
| Tool | What it does |
| ---------------------------------- | ------------------------------------------------------------------------ |
| `list_supplier_team_members` | Lists supplier team members with names, emails, role, and current flags. |
| `list_supplier_team_invites` | Lists pending supplier team invites. |
| `invite_supplier_team_member` | Invites a teammate when the signed-in supplier user can manage the team. |
| `remove_supplier_team_member` | Removes a teammate by email when permitted. |
| `update_supplier_team_member_role` | Changes a teammate role to admin or regular when permitted. |
| `get_supplier_analytics_summary` | Reads supplier dashboard analytics and profile completeness. |
## Admin tools
Admin tools require a CivicMarketplace admin account plus `admin:read` or `admin:write`.
| Tool family | Tools |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Search records | `admin_search_suppliers`, `admin_search_agencies`, `admin_search_coops`, `admin_search_contracts` |
| Get records | `admin_get_supplier`, `admin_get_agency`, `admin_get_coop`, `admin_get_contract` |
| Create records | `admin_create_supplier`, `admin_create_agency`, `admin_create_coop`, `admin_create_contract` |
| Update records | `admin_update_supplier`, `admin_update_agency`, `admin_update_coop`, `admin_update_contract` |
| Contract status | `admin_set_contract_status` |
| Supplier relationships | `admin_add_supplier_nigp_codes`, `admin_remove_supplier_nigp_codes`, `admin_set_supplier_nigp_codes`, `admin_add_supplier_tags`, `admin_remove_supplier_tags`, `admin_set_supplier_tags`, `admin_add_supplier_categories`, `admin_remove_supplier_categories`, `admin_set_supplier_categories`, `admin_add_supplier_certifications`, `admin_remove_supplier_certifications`, `admin_set_supplier_certifications`, `admin_add_supplier_regions`, `admin_remove_supplier_regions`, `admin_set_supplier_regions` |
| Contract relationships | `admin_add_contract_suppliers`, `admin_remove_contract_suppliers`, `admin_set_contract_suppliers`, `admin_add_contract_nigp_codes`, `admin_remove_contract_nigp_codes`, `admin_set_contract_nigp_codes`, `admin_add_contract_tags`, `admin_remove_contract_tags`, `admin_set_contract_tags`, `admin_add_contract_themes`, `admin_remove_contract_themes`, `admin_set_contract_themes`, `admin_add_contract_city_services`, `admin_remove_contract_city_services`, `admin_set_contract_city_services` |
| Agency relationships | `admin_add_agency_cooperatives`, `admin_remove_agency_cooperatives`, `admin_set_agency_cooperatives` |
Some write tools create new records or send notifications. Relationship set/remove tools and quote
request archive/cancel tools can change existing state. Your AI assistant may ask for confirmation
before using these tools depending on its own MCP permission settings.