MCP Tools

Full parameter reference for all 20 tools exposed by the MCP server. Each tool is a thin wrapper over the corresponding v1 use case, so responses match the REST API contracts.

Tools are grouped by scope:

• Public tools (6) read public procurement data and are available to any key with MCP enabled.
• Account tools (10) read data belonging to the account that owns the API key. The account is resolved from the key — never passed as a parameter.
• Account write tools (4) modify that account's data. 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.

---

Public tools

search_tenders

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

Parameter	Type	Description
text	string?	Full-text search query
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, e.g. ["45000000-7"]
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. 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}.

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. Equivalent to GET /v1/organizations/{idOrSlug}/awards.

---

Account tools

These tools read data scoped to the account that owns the API key.

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