MCP Tools

Parameter reference for tools exposed by the MCP server. Execution tools reuse application use cases with MCP-specific presentation. Discovery describes the registered catalog without executing those tools.

Tools are grouped by scope:

• Public tools read public procurement data and are available to every MCP connection.
• Account tools read data belonging to the account you connected to: the account chosen when signing in, or the one that owns the API key. It is never passed as a parameter.
• Account write tools modify that account's data. Read-only connections don't see them. See Writing data for the confirmation rules.

Where a parameter accepts a "reference", you can pass the ID from a previous tool's references block or a Tendios URL copied from the browser.

All tools

Tool	Scope	Purpose
find_tools	Discovery	Suggest the tools for a task described in plain language
search_tenders	Public	Full-text and faceted search over tenders
get_tender	Public	Full details of one tender by id
get_tender_sheets	Public	Documents attached to a tender
get_cpv	Public	Details of a CPV code
get_organization	Public	Organization profile by id or slug
search_organizations	Public	Resolve an organization name or tax ID to its id
get_organization_award_stats	Public	Award statistics by year for an organization
list_market_scopes	Public	Supplier families and buyer perimeters for market awards
get_market_awards	Public	Awards of a supplier family over a period
whoami	Account	Which account, organization, and plan you are acting on
list_alerts	Account	Every alert configured for the account
get_alert	Account	Full configuration of one alert
get_alert_results	Account	Tenders matching one of your saved alerts
list_pipelines	Account	Pipelines and their stages, with the IDs other tools need
get_kanban_status_totals	Account	Opportunity totals per pipeline status
get_kanban_opportunities_by_status	Account	Paginated opportunities in one pipeline status
search_kanban_opportunities	Account	Search a pipeline, grouped by status
get_opportunity_workflow_actions	Account	Workflow action records for an opportunity
list_opportunity_tasks	Account	Tasks attached to an opportunity
create_alert	Account write	Create a new alert
update_alert	Account write	Change fields on an existing alert
change_opportunity_status	Account write	Move an opportunity to another pipeline stage
create_opportunity_task	Account write	Add a task to an opportunity

---

Tool discovery

find_tools

Describe a task in English or Spanish when unsure which tool to use.

Parameter	Type	Description
intent	string	Task description, 3–500 characters

Returns up to eight registered tools with their exact JSON input schemas, descriptions, annotations, prerequisites, and guidance. recommendedSequence describes the strongest match. Prerequisites can be skipped when the required references are already known. Ranking is deterministic keyword matching, not an AI planner; unknown intents return no matches. It makes no database/AI calls, executes no actions, and changes no permissions or confirmation requirements.

All execution tools remain exposed normally. This helper does not unload schemas from client context; that behavior is controlled by the MCP client. Reconnect clients after adding tools to refresh their catalog.

Example: {"intent":"How many tenders did Accenture win in Spain?"} recommends list_market_scopes → get_market_awards. Resolve the supplier family, obtain the publication period, omit buyerPerimeterId, set countryCode: "ES", and read summary.totalContracts. A regional buyer perimeter cannot stand in for a country-wide question.

Example: {"intent":"¿Quién ganó licitaciones de carreteras en España?"} recommends search_tenders first. Use CPV filters, awarded/formalized status and locations: ["country/ES"]; inspect recorded awardees, then resolve an organization and request its statistics if needed. No supplier family or buyer perimeter is required for sector-level winner discovery. For "Identify all suppliers awarded contracts by Carreteras del Estado in 2026", discovery recommends search_organizations → search_tenders: resolve the relevant authorities, pass their IDs and award-date bounds. This finds matching tenders, but does not guarantee a complete supplier ranking: pagination, missing tender-level winners, and unexposed lot winners limit that analysis.

Public tools

search_organizations

Resolve an organization name or tax ID to existing operational IDs before calling get_organization or get_organization_award_stats.

Parameter	Type	Description
text	string	Name or tax-ID substring, 2–200 characters; case-insensitive
type	string?	bidder or public-contracting-institution
page	number?	One-based page, default 1, maximum 1000
pageSize	number?	Default 10, maximum 50

Returns organizations with id, name, taxId, type, country, and known alias slugs, plus pagination with hasNextPage. Deleted, hidden, and user-created records are excluded before pagination; buyers without tax IDs remain searchable. No contact enrichment or private account data is returned. This searches recorded organization names/tax IDs, not corporate relationships or a fuzzy alias index. Multiple matches must be disambiguated; do not guess slugs or sum potentially duplicate organization statistics. For consolidated supplier-family awards use list_market_scopes and get_market_awards.

list_market_scopes and get_market_awards

list_market_scopes resolves approved active supplier-family and buyer-perimeter IDs. get_market_awards requires a supplier-family ID and publication-date bounds. Buyer perimeter is optional; countryCode narrows the account's permitted tender-location countries. These tools require existing approved definitions; discovery never creates or approves them. See the repository's docs/market-awards.md for configuration and the local fixture example.

search_tenders

Search tenders by text and filters (status, CPVs, locations, budget, date ranges).

Results include successBidderOrganization (ID and name) when recorded, plus organization references for get_organization. Search by sector or CPV and filter awarded results to inspect who won; a curated supplier family is not required. Missing awardees are not inferred.

Results show the recorded award date (adjudicatedAt) alongside publication and submission dates. by-awarding-date sorts on the search index's award date, not publication date. Pagination includes totalRelation: eq means an exact count; gte means a lower bound. For example, total: 10000, totalRelation: "gte" means at least 10,000, not exactly 10,000. This search does not request an uncapped exact market-size count.

Parameter	Type	Description
text	string?	Analyzed AND search; double quotes select phrase matching
page	number?	Page number (1-based, default 1)
pageSize	number?	Results per page (default 10, max 100)
sort	string?	Sort field — see sort values (default by-published-date)
isDescendent	boolean?	Sort descending (default true)
status	string[]?	Filter by tender status
cpvs	string[]?	Filter by CPV codes with or without the check digit, e.g. ["45000000-7"] or ["45000000"]
locations	string[]?	Filter by location: country/<ISO-2> or town/<name>, e.g. ["country/ES"]
procedures	string[]?	Filter by procedure types
contractTypes	string[]?	Filter by contract types
minBudget	number?	Minimum budget (no tax)
maxBudget	number?	Maximum budget (no tax)
minPublicationDate	string?	Minimum publication date (ISO 8601)
maxPublicationDate	string?	Maximum publication date (ISO 8601)
minDeadlineDate	string?	Minimum submission deadline (ISO 8601)
maxDeadlineDate	string?	Maximum submission deadline (ISO 8601)

Returns a { data, pagination } envelope. Additional organization and award-date filters:

Parameter	Type	Description
contractingOrganizationIds	string[]?	Match any buyer ID, including recorded child authorities; resolve IDs with search_organizations. Up to 100 IDs.
successBidderOrganizationIds	string[]?	Match any supplier ID on the tender or its lots. Up to 100 IDs.
minAwardingDate	string?	Inclusive minimum recorded award timestamp, ISO 8601 with timezone.
maxAwardingDate	string?	Inclusive maximum recorded award timestamp, ISO 8601 with timezone.

Organization lists use OR within each list; buyer, supplier and date filters combine with AND. For awards during calendar year 2026, use 2026-01-01T00:00:00Z through 2026-12-31T23:59:59.999Z. Publication dates do not need to fall in that year. Supplier filtering can match lot-level winners even when the returned tender-level winner differs or is absent. Each result is a tender, not an individual lot or award event.

Text searches tender and lot titles/descriptions. Unquoted text uses analyzed, stemmed terms with AND matching; double-quoted text uses phrase matching on the unstemmed fields. Phrases and remaining free terms must all match. The search also attempts public-reference matching. Neither mode filters by a buyer's identity: use contractingOrganizationIds for that. Phrase-search counts are not a count of all contracts from the named authority. Explicit match modes, field selection and matched snippets are not currently exposed.

Equivalent to POST /v1/tenders/search.

get_tender

Retrieve the full details of a single tender by its id.

Parameter	Type	Description
id	string	The tender id

Equivalent to GET /v1/tenders/{id}.

Tender details include the recorded successBidderOrganizationId, resolved winner name when available, and a successBidderOrganization follow-up reference. If the organization record is missing, its recorded ID is preserved without inventing a name.

get_tender_sheets

List the sheets (documents) attached to a tender by tender id.

Parameter	Type	Description
id	string	The tender id

Returns document metadata only. To download a file, use GET /v1/tenders/sheets/{sheetId}/download — binary streams are not exposed as MCP tools.

get_cpv

Get the details of a CPV (Common Procurement Vocabulary) code.

Parameter	Type	Description
code	string	The CPV code, e.g. 72000000

Returns the code's type (division, group, class, category) and its name in each supported language. Equivalent to GET /v1/cpv/{code}.

get_organization

Get an organization profile by its id or slug.

Parameter	Type	Description
idOrSlug	string	The organization id (e.g. the contractingOrganizationId of a tender) or slug, e.g. altia-consultores-sa

Works for both bidders and public contracting institutions. Equivalent to GET /v1/organizations/{idOrSlug}.

get_organization_award_stats

Get award statistics by year for an organization, identified by its id or slug.

Parameter	Type	Description
idOrSlug	string	The organization id (e.g. the contractingOrganizationId of a tender) or slug, e.g. altia-consultores-sa

Returns yearly totals plus a CPV sector breakdown. Both cover tenders with recorded award dates. Each tender counts once per CPV division, but may belong to several divisions; sector counts must not be summed as unique awards. Tenders without a mapped division are absent from that breakdown. Sector percentages use the sum of tender-sector memberships as their denominator, not unique tenders. Equivalent to GET /v1/organizations/{idOrSlug}/awards.

---

Account tools

These tools read data scoped to the account you connected to.

whoami

Get the authenticated principal, account, linked organization, and active Bid plan.

Takes no parameters.

Use it as an orientation call — it tells an assistant which account it is acting on before it reads or changes anything. Equivalent to GET /v1/whoami.

list_alerts

List every alert configured for the account, with references for retrieving their results.

Parameter	Type	Description
text	string?	Filter alerts by title
isArchived	boolean?	Filter archived or non-archived alerts
page	number?	Page number (1-based, default 1)
pageSize	number?	Alerts per page (default 20, max 100)
sort	string?	Sort field — see alert sort values (default by-update-date)
sortDirection	string?	asc or desc (default desc)

Returns references.alerts[] for use with get_alert, update_alert, and get_alert_results. Equivalent to GET /v1/alerts.

get_alert

Get the current configuration of one alert.

Parameter	Type	Description
alert	string	Alert reference from list_alerts, or its Tendios URL

Equivalent to GET /v1/alerts/{alertId}.

get_alert_results

Get the tenders matching one of your saved alerts, by alert id. The alert's own criteria are applied first; text filters further on top of them.

Parameter	Type	Description
alertId	string	The alert id
text	string?	Additional text filter on top of the alert criteria
page	number?	Page number (1-based, default 1)
pageSize	number?	Results per page (default 10, max 100)
sort	string?	Sort field — see sort values (default by-published-date)
isDescendent	boolean?	Sort descending (default true)

Returns a paginated result. This is the tool to use for building automated tender feeds from an alert you already maintain in Bid.

list_pipelines

List the opportunity pipelines and stages configured for your account, including the IDs the kanban and opportunity tools need.

Parameter	Type	Description
page	number?	Page number (1-based, default 1)
pageSize	number?	Pipelines per page (default 20, max 100)

Returns references.pipelines[], each with a pipeline reference and its statuses references. Start here — every other pipeline tool accepts the UUIDs or the exact names this returns. Equivalent to GET /v1/pipelines.

get_kanban_status_totals

Get the opportunity totals per pipeline status for a kanban board in your account.

Parameter	Type	Description
pipelineId	string	Pipeline UUID or exact pipeline name from list_pipelines
responsible	string[]?	Filter by responsible user ids
teamResponsible	string[]?	Filter by responsible team ids

Useful as a first call — it gives an assistant the shape of the board (which statuses exist and how many opportunities sit in each) before drilling into a column.

get_kanban_opportunities_by_status

Get a paginated list of opportunities in a specific pipeline status (kanban column).

Parameter	Type	Description
pipelineId	string	Pipeline UUID or exact pipeline name from list_pipelines
statusId	string	Stage UUID or exact stage name from list_pipelines
page	number?	Page number (1-based, default 1)
pageSize	number?	Results per page (default 10, max 100)
sort	string?	Sort order — see opportunity sort values
sortDirection	string?	asc or desc (default asc)

search_kanban_opportunities

Search opportunities within a pipeline, grouped by status. Returns up to limit opportunities per status.

Parameter	Type	Description
pipelineId	string	Pipeline UUID or exact pipeline name from list_pipelines
limit	number?	Max opportunities per status (default 10, max 50)
search	string?	Search term to filter opportunities
sort	string?	Sort order — see opportunity sort values
sortDirection	string?	asc or desc (default asc)
responsible	string[]?	Filter by responsible user ids
teamResponsible	string[]?	Filter by responsible team ids

Unlike the other paginated tools, this one returns a map of statusId → array of opportunities rather than a { data, pagination } envelope — it reads a whole board in one call.

get_opportunity_workflow_actions

Get the current workflow action records for an opportunity, grouped by workflow step.

Parameter	Type	Description
opportunity	string	Opportunity UUID or Tendios opportunity URL

Shows which qualification steps are done and which are outstanding. Equivalent to GET /v1/opportunities/{opportunityId}/workflow-actions.

list_opportunity_tasks

List tasks associated with an opportunity, optionally filtered by status.

Parameter	Type	Description
opportunity	string	Opportunity UUID or Tendios opportunity URL
status	string?	Filter by task status
page	number?	Page number (1-based, default 1)
pageSize	number?	Tasks per page (default 20, max 100)

Equivalent to GET /v1/opportunities/{opportunityId}/tasks.

---

Account write tools

These four tools modify your account. Read Writing data first — two of them refuse to act until you confirm.

create_alert

Create an alert. The tool is designed to be driven conversationally: it expects the assistant to gather the configuration, summarize it, and get your explicit approval before committing.

Parameter	Type	Description
title	string	Readable alert name
events	object[]	Tender events that trigger the alert (min 1) — see below
description	string?	Free-text description
criteria	object?	Tender matching criteria — see below
notification	object?	Delivery schedule — see below
responsibleUserIds	string[]?	Account user IDs that receive alert emails; omit for no recipients
isActive	boolean?	Active immediately (default true)
isPublic	boolean?	All account users can access it (default true)
confirmed	boolean?	Required to actually create. Set true only after the user confirms

Called without confirmed: true, the tool returns an error result asking the assistant to summarize and confirm first.

events[]

Field	Type	Description
event	string	publication, award, or deadline
expirationOffset	number?	Days before the deadline to notify — deadline only (default 1)
withExtension	boolean?	Use the extended deadline — deadline only (default false)

These friendlier names map onto the REST API's windowsSearch fields (expedientPublishedAt, expedientAdjudicationDate, expedientExpirationDate).

criteria — every field optional:

Field	Type	Description
keywords	object	{ include: string[], exclude: string[] }
cpvCodes	object	{ include: string[], exclude: string[] }
countries	object	{ include: string[], exclude: string[] }
provinces	object	{ include: string[], exclude: string[] }
budget	object	{ min, max }
statuses	string[]	Tender status values (min 1 when present)
contractTypes	string[]	Contract type values
procedures	string[]	Procedure type values
inDeadline	boolean	Only tenders still open for submission

notification — every field optional:

Field	Type	Description
frequency	string	daily or weekly
weekdays	number[]	Days for a daily schedule, 1 = Monday … 7 = Sunday
weeklyDay	number	Day for a weekly schedule, 1–7
hour	number	Delivery hour, 0–23
timezone	string	IANA zone, e.g. Europe/Madrid
includeModifications	boolean	Include modified tenders, not just new ones
sendWithoutItems	boolean	Send the email even when nothing matched

Supplying weeklyDay alone implies a weekly schedule; weekdays alone implies daily.

update_alert

Update selected fields of an existing alert. Omitted fields stay unchanged; empty include/exclude arrays clear those filters.

Parameter	Type	Description
alert	string	Alert reference from list_alerts/get_alert, or its Tendios URL
title	string?	New title
description	string?	New description
events	object[]?	Replace the triggering events — same shape as create_alert
criteria	object?	Replace criteria — same shape as create_alert
notification	object?	Replace schedule — same shape as create_alert
responsibleUserIds	string[]?	Replace email recipients
isActive	boolean?	Pause or resume
isPublic	boolean?	Change visibility
isArchived	boolean?	Archive or unarchive

Unlike create_alert, this one needs no confirmation flag — it is idempotent and reversible. Changing only hour keeps an existing weekly schedule weekly. Equivalent to PATCH /v1/alerts/{alertId}.

change_opportunity_status

Move an opportunity to another stage in its current pipeline.

Parameter	Type	Description
opportunity	string	Opportunity UUID or Tendios opportunity URL
targetStatus	string	Target stage UUID or exact stage name from list_pipelines
confirmTerminal	boolean?	Required for terminal stages. Set true only after the user confirms

Behaviour worth knowing:

• If the opportunity is already in the target stage, the tool says so and changes nothing.
• If the target stage is terminal and confirmTerminal is not true, it returns an error result asking for confirmation, because reaching a terminal stage may close the opportunity.
• It is the only tool annotated as destructive.

Equivalent to PUT /v1/opportunities/{opportunityId}/status.

create_opportunity_task

Create a task on an opportunity, gathering the details conversationally first.

Parameter	Type	Description
opportunity	string	Opportunity UUID or Tendios opportunity URL
title	string	Readable task title
description	string?	Additional instructions
status	string?	Task status (default to-do)
priority	string?	Task priority (default medium)
responsibleUserIds	string[]?	Account user IDs assigned to the task
deadlineAt	string?	ISO 8601 deadline
confirmed	boolean?	Required to actually create. Set true only after the user confirms

Equivalent to POST /v1/opportunities/{opportunityId}/tasks.

---

Enum values

Tender sort values

Accepted by search_tenders and get_alert_results. Default is by-published-date.

Value	Sorts by
by-relevance	Full-text relevance score
by-published-date	Publication date
by-update-date	Last update date
by-due-date	Submission deadline
by-budget	Budget without tax
by-prorated-budget	Prorated budget
by-expiration-date	Expiration date
by-awarding-date	Awarding date
by-last-significant-change	Last significant change

Direction is controlled by isDescendent (default true).

Opportunity sort values

Accepted by get_kanban_opportunities_by_status and search_kanban_opportunities.

Value	Sorts by
custom	The manual order set on the board
by-update-date	Last update date
by-due-date	Due date
by-budget	Budget
by-prorated-budget	Prorated budget

Direction is controlled by sortDirection (asc or desc, default asc).

Alert sort values

Accepted by list_alerts. Default is by-update-date.

Value	Sorts by
by-name	Alert title
by-update-date	Last update date
by-creation-date	Creation date
by-last-notified-date	Last time the alert matched
by-last-notification-sent-date	Last time an email was sent
by-status	Active/inactive state

Direction is controlled by sortDirection (asc or desc, default desc).

Task status and priority values

Accepted by list_opportunity_tasks (status) and create_opportunity_task (status, priority).

status	Meaning
to-do	Not started (the default)
in-progress	Being worked on
done	Completed

priority	Meaning
high	High priority
medium	Medium (the default)
low	Low priority