MCP Tool Reference

This page provides the complete input schema and parameter details for every tool available through the TeamCentral MCP API. For an overview of tools and how to get started, see MCP API.

Data Models

get_data_models

Returns a list of Data Models that have been configured.

Parameters: None

---

get_data_model_properties

Gets the properties of a Data Model. Must first call get_data_models to get a dataModelId.

Parameters:

Name	Type	Required	Description
dataModelId	GUID	Yes	The Data Model ID from get_data_models

References in the output: a property that is a tie to another entity has dataType: "Reference" and a reference object. Its propertyName is what you pass to expand, to a reference filter, or to a reference group key. The reference object includes:

Field	Description
direction	Outbound (this entity holds the foreign key to one related entity) or Inbound (other entities point back at this one — a derived collection)
cardinality	OneToOne (single related entity) or OneToMany (a collection)
targetEntityType / targetEntitySubType	The related entity's type
targetDataModelId	The related Data Model's ID (for follow-up queries); may be null if the target has no Data Model
expandable	Whether you may load it inline — false when you lack access to the target model
derived	true for Inbound collections (the reverse view of another entity's foreign key; read-only)

See Working with related data for an overview.

Entity Lookup & Query

lookup_by_keyword

Searches for foreign key-related entities by keyword. Must first call get_data_models to get an entityType and entitySubType, or get them from get_data_model_properties. If multiple entities are returned, the user should choose which one to use.

Parameters:

Name	Type	Required	Description
searchValue	string	Yes	The keyword to search for
entityType	string	No	Entity type from get_data_models
entitySubType	string	No	Entity sub-type from get_data_models
limit	integer	No	Max results to return (1–100, default 10)

---

query_entities

Queries for entities using filters, sorting, pagination, and optional property selection. This is the most flexible query tool, supporting complex filter groups with AND/OR logic and property-to-property comparisons.

Prerequisites:

• Call get_data_models to get a dataModelId
• Call get_data_model_properties to find valid property names for filters
• Call lookup_by_keyword if a property is a foreign key, to get the entity ID (GUID) for comparison

If results contain File entities with an externalFileLocation property, use get_file_text to extract readable content.

Parameters:

Name	Type	Required	Description
dataModelId	GUID	Yes	The Data Model ID from get_data_models
queryParameterGroups	array	No	Filter groups (see Query Parameter Groups below)
paging	object	No	Pagination settings (see Paging below)
sortCondition	object	No	Sort settings (see Sort Condition below)
countOnly	boolean	No	When true, returns only the count without entity data (default false)
properties	string[]	No	Property names to include in results. Only these fields (plus id) are returned. Omit to return all fields.
expand	array	No	Related entities to load inline (see References and expansion below)

Query Parameter Groups

Each group contains an array of filter parameters combined with AND/OR logic. Multiple groups are supported for complex queries.

Name	Type	Required	Description
andOrOperator	enum	No	And or Or (default And)
parameters	array	No	Array of filter parameters (see below)

Filter Parameters:

Name	Type	Required	Description
operator	enum	Yes	One of: EqualTo, NotEqualTo, GreaterThan, GreaterThanEqualTo, LessThan, LessThanEqualTo, Contains, StartsWith, NotStartsWith, EndsWith, NotEndsWith
propertyName	string	Yes	A valid property name from get_data_model_properties
value	string	Conditional	The comparison value. For foreign key properties, provide the entity ID (GUID). Use the string "null" for null comparisons. Not required when comparisonPropertyName is set.
valueType	enum	Conditional	boolean, string, number, or null. Use null when the value is null. Not required when comparisonPropertyName is set.
comparisonPropertyName	string	No	When set, compares propertyName against this property instead of value. Must be a valid property from get_data_model_properties.
reference	string	No	When set, the filter applies to a property of a related entity reached via this reference (a Reference property from get_data_model_properties). propertyName then names a property on the target entity.
match	enum	No	For an Inbound/OneToMany reference filter: Any (default) matches when at least one related entity satisfies the predicate (EXISTS). Ignored for Outbound/OneToOne references.

Filter on a related entity

To find Invoices whose related Customer is in a given industry, set reference to Customer, propertyName to IndustryVertical, operator to EqualTo, and value to the industry. For a OneToMany reference (e.g. Customers that have a large Invoice), set match to Any.

Property-to-property comparison

To find records where one field exceeds another — for example, where UpdatedDate is after CreatedDate — set propertyName to UpdatedDate, comparisonPropertyName to CreatedDate, and operator to GreaterThan. When using comparisonPropertyName, omit value and valueType.

Paging

Name	Type	Required	Description
pageNumber	integer	No	Page to retrieve, 1-based (default 1)
pageSize	integer	No	Items per page, 1–100 (default 25)

The response includes hasMore (boolean) and nextPage (number or null). If nextPage is non-null, pass it as pageNumber in the next request to continue.

Sort Condition

Name	Type	Required	Description
propertyName	string	Yes	Property name from get_data_model_properties
sortOrder	enum	No	Ascending or Descending (default Ascending)

References and expansion

The expand parameter loads related entities inline, returning an entity and its related data in one call. Each entry names a reference (from get_data_model_properties) and, optionally, which of its fields to return.

Name	Type	Required	Description
reference	string	Yes	A reference name from get_data_model_properties (a property with dataType: "Reference")
properties	string[]	No	Fields to return from the related entity. The related id is always included. Omit to return all fields.

Expanded data is attached under properties.expanded.<referenceName> on each result:

• Outbound / OneToOne → a single nested object (null when there is no related entity).
• Inbound / OneToMany → an array ([] when there are none).

Expansion is shallow (expanded entities are not themselves expanded). A OneToMany expansion returns at most 100 related entities per parent; when capped, the parent carries an ExpandedTruncated marker listing the affected references — narrow with a filter or paging if you hit it.

"expanded": {
  "customer": { "name": "Acme", "region": "APAC" },
  "invoice": [ { "transactionId": "616560", "amountTotal": 1450, "id": "…" } ]
}

---

aggregate_entities

Computes aggregate values — Sum, Average, Count, Min, Max, and DistinctCount — over a filtered set of entities, optionally grouped by one or more properties. Use this instead of paging through every record when you only need totals or per-group rollups.

Prerequisites:

• Call get_data_models to get a dataModelId
• Call get_data_model_properties to find valid property names for aggregations and grouping
• Call lookup_by_keyword if filtering on a foreign key, to get the entity ID (GUID)

Sum, Average, Min, and Max require numeric properties (Int, Long, Double, or Decimal). Count counts matching rows and takes no property. DistinctCount counts distinct non-null values of a property.

Parameters:

Name	Type	Required	Description
dataModelId	GUID	Yes	The Data Model ID from get_data_models
aggregations	array	Yes	One or more aggregates to compute (see Aggregations below)
queryParameterGroups	array	No	Filter groups applied before aggregating — same shape as query_entities (see Query Parameter Groups above)
groupBy	array	No	Group keys, each { propertyName, reference? }. Omit for a single totals row; provide to get one row per distinct combination. Set reference to group by a property on a related entity (see Across related entities below).

Aggregations

Name	Type	Required	Description
function	enum	Yes	One of: Sum, Average, Count, Min, Max, DistinctCount
propertyName	string	Conditional	Property to aggregate. Required for all functions except Count. Must be numeric for Sum/Average/Min/Max.
alias	string	No	Output key for this value in the result. Defaults to {function}_{propertyName}. Result keys are returned camelCased (first letter lowercased), consistent with entity property keys — e.g. a Sum of Amount is returned under sum_Amount.
joinFilter	object	No	Count/aggregate only the base rows whose cross-entity condition holds — used for conditional ratios like On-Time % (see Conditional cross-entity aggregates below)

Response:

The response contains matchedCount (records matched by the filter), groupByProperties, and rows. Each row has a groupKey (the group's values, empty when not grouping) and aggregates (each alias mapped to its computed value).

{
  "matchedCount": 14999,
  "groupByProperties": ["WarehouseId"],
  "rows": [
    { "groupKey": { "warehouseId": "d5c3…" }, "aggregates": { "sum_Amount": 15599196.11, "sum_Quantity": 32024 } }
  ]
}

Ratio KPIs

To compute a ratio such as "cost per unit", request both the numerator and denominator in one call — for example, a Sum of cost and a Sum of units shipped — and divide the two returned totals. Add groupBy to break the ratio down per warehouse, product, region, and so on.

Grouped queries

Grouped aggregations read the matching set to roll it up, so they are capped at a bounded number of records. If a grouped query matches too many records it is rejected — narrow the set with queryParameterGroups (for example, a date range). Ungrouped totals have no such limit.

Across related entities

• Filter by a related property: queryParameterGroups accepts the same reference filters as query_entities — aggregate only the rows whose related entity matches (e.g. invoices whose Customer is in a given region).
• Group by a related property: set reference on a groupBy entry to roll up by a field on the related entity (e.g. invoice totals by Customer industry). The group-key label is reference.propertyName (first segment camelCased); rows with no related value fall into a null group rather than being dropped.
• OneToMany group keys fan out: grouping by an Inbound/OneToMany reference puts a row in each distinct related value (e.g. a customer appears under every opportunity stage it has); its measures are counted once per distinct value.

Conditional cross-entity aggregates (joinFilter)

A joinFilter on an aggregation clause includes a base row only when a condition against a joined entity holds. Put a joinFilter on one clause and leave another unconditional, then divide — the pattern for ratios like On-Time Shipment %.

Field	Type	Required	Description
reference	string	Conditional	Named reference to the joined entity (preferred). Provide this or entity + on.
entity	string	Conditional	Explicit joined entity type (escape hatch); requires on.
on	object	Conditional	Explicit join keys { localProperty, foreignProperty } (base foreign key → joined key), used with entity.
condition	object	Yes	The per-row test (below)

Condition:

Field	Type	Required	Description
localProperty	string	Yes	Property on the base entity
operator	enum	Yes	Same operators as query filters
foreignProperty	string	Conditional	Property on the joined entity to compare against (cross-entity). Provide this or value.
value	string	Conditional	Literal to compare against. Provide this or foreignProperty.

Example — On-Time Shipment %:

"aggregations": [
  { "function": "Count", "alias": "total" },
  { "function": "Count", "alias": "on_time",
    "joinFilter": { "reference": "Customer",
      "condition": { "localProperty": "DueDate", "operator": "LessThanEqualTo", "foreignProperty": "RenewalDate" } } }
]

Date comparisons

Ordering comparisons are typed off the base property: when it is a Date field, both sides compare chronologically. If the base property is a string, the comparison is lexicographic — reliable only for uniformly formatted ISO-8601 dates.

Current limits

joinFilter supports 1-to-1 joins only and cannot be combined with groupBy yet — request those separately. Aggregating over a related collection (e.g. summing a parent's child values) is not yet supported.

---

get_entities_by_ids

Retrieves one or more entities by their unique IDs from a specific Data Model. For a single entity, pass an array with one ID. Non-existent IDs are silently omitted from the results.

If a result is a File entity with an externalFileLocation property, use get_file_text to extract readable content.

Parameters:

Name	Type	Required	Description
dataModelId	GUID	Yes	The Data Model ID from get_data_models
entityIds	GUID[]	Yes	Array of entity IDs to retrieve (1–50)
properties	string[]	No	Property names to include in results. Only these fields (plus id) are returned. Omit to return all fields.
expand	array	No	Related entities to load inline — same shape as References and expansion on query_entities

Saved Queries

get_saved_queries

Returns all Saved Queries (Live Data Providers) accessible to the user. Each query includes its name, ID, connector info, data model info, and declared input parameters.

Parameters: None

---

get_saved_query_details

Returns detailed metadata for a specific Saved Query, including its mapped fields (property names, types, and descriptions) filtered by user permissions. Must first call get_saved_queries to get the savedQueryId.

Parameters:

Name	Type	Required	Description
savedQueryId	GUID	Yes	The Saved Query ID from get_saved_queries

---

execute_saved_query

Executes a Saved Query by its ID with the provided input parameters. Must first call get_saved_queries to get the savedQueryId and declared inputs.

If results contain File entities with an externalFileLocation property, use get_file_text to extract readable content.

Parameters:

Name	Type	Required	Description
savedQueryId	GUID	Yes	The Saved Query ID from get_saved_queries
inputs	array	No	Input parameters matching DeclaredInputs from get_saved_queries (see below)
properties	string[]	No	Property names to include in results. Only these fields (plus id) are returned. Omit to return all fields.

Input Parameters:

Name	Type	Required	Description
key	string	Yes	Input name from DeclaredInputs
value	string	Yes	Value for the input

Data Entry

get_data_entry_form

Retrieves a data entry form for a Data Model, optionally pre-populated with initial values. Must first call get_data_models to get a dataModelId. Send the output of this tool to submit_data_entry_form when complete.

Parameters:

Name	Type	Required	Description
dataModelId	GUID	Yes	The Data Model ID from get_data_models
format	enum	Yes	AdaptiveCard or Json — use the most appropriate format for the calling client
initialValues	array	No	Key-value pairs to pre-populate the form (see below)

Initial Values:

Name	Type	Required	Description
key	string	Yes	Property name from get_data_model_properties
value	string	Yes	Initial value for the field

---

submit_data_entry_form

Submits a completed data entry form to create or update a record.

Destructive

This tool creates or modifies records. The AI assistant will confirm with the user before submitting.

Parameters:

Name	Type	Required	Description
dataModelId	GUID	Yes	The Data Model ID — should match the one passed to get_data_entry_form
system	enum	No	The submitting system: Corbi, ChatGPT, Claude, or Copilot
formValues	array	Yes	Completed form values (see below)

Form Values:

Name	Type	Required	Description
key	string	Yes	Property name from get_data_model_properties
value	string	Yes	Submitted value for the field

File Extraction

get_file_text

Extracts readable text from a document URL. Supports PDF, DOCX, PPTX, HTML, TXT, MD, CSV, JSON, and XML formats. Returns text in chunks — call repeatedly using the nextOffset value from the response until hasMore is false.

Parameters:

Name	Type	Required	Description
url	URL	Yes	The externalFileLocation URL from the entity
offset	integer	No	Start at 0, then use nextOffset from the previous response (default 0)