Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bsdd-mcp What properties does IfcWall have?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives an AI assistant read-only access to the buildingSMART Data Dictionary (bSDD) — the shared library of construction classifications (IFC, ETIM, Uniclass, national dictionaries, …), their classes, properties, units and relations.
It talks to the public bSDD API at https://api.bsdd.buildingsmart.org. No account, API key or
login is needed: every endpoint used here is part of the unsecured, public API.
git clone <this repo>
cd bsdd-mcp
npm install # builds automatically via the prepare scriptRelated MCP server: IFCX MCP
claude mcp add bsdd -- node /absolute/path/to/bsdd-mcp/dist/index.jsCowork installs local MCP servers as .mcpb bundles. Build one:
npm run bundle # -> build/bsdd-mcp-<version>.mcpbThe bundle is self-contained (compiled server + production dependencies), so it does not
depend on this checkout after installation. Install it from Settings → Connectors →
Install extension… and pick the .mcpb file. Local MCP servers run natively on your
machine, not inside the Cowork sandbox, so the server reaches the bSDD API over your normal
network connection.
If your workplace disables desktop extensions, add the server by hand instead under Settings → Developer → Local MCP servers:
{
"mcpServers": {
"bsdd": {
"command": "node",
"args": ["C:\\path\\to\\bsdd-mcp\\dist\\index.js"]
}
}
}Add this to the client's MCP configuration (claude_desktop_config.json for Claude Desktop):
{
"mcpServers": {
"bsdd": {
"command": "node",
"args": ["C:\\path\\to\\bsdd-mcp\\dist\\index.js"]
}
}
}Tool | What it does | bSDD endpoint |
| List/filter the published dictionaries |
|
| Browse the classes of one dictionary (flat or nested) |
|
| Browse the properties of one dictionary |
|
| Free-text class search across dictionaries |
|
| Free-text search returning classes and properties |
|
| Class details, optionally with child classes and relations |
|
| The properties of a class, with data types and units |
|
| Forward or reverse relations of a class |
|
| Property details |
|
| Which classes use a property |
|
| Details of one value of an enumeration |
|
| Countries, languages, units or reference documents |
|
All tools are read-only and annotated as such.
bsdd_list_dictionaries — find the dictionary URI you need. URIs always contain a version,
e.g. https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3; the version can be
replaced by latest.
bsdd_search_classes — find a class by name, e.g. "which class describes a wall?".
bsdd_get_class for the definition, bsdd_get_class_properties for its properties,
bsdd_get_class_relations to map it onto classes in other dictionaries.
All optional, read from the environment:
Variable | Default | Purpose |
|
| Point at another bSDD instance |
|
| Per-request timeout |
|
| Retries on HTTP 429 / 5xx |
|
| User-Agent sent to bSDD |
These are behaviours of the upstream API that the server works around, and that are worth knowing when reading the results:
Rate limiting. bSDD answers with HTTP 429 and a message like "Try again in 4 seconds".
The client honours Retry-After (and that message) and retries with exponential backoff.
IFC and text search. /api/TextSearch/v2 treats the IFC dictionary as a preview dictionary
and leaves it out unless IncludePreview is set, so bsdd_search_text sets it by default.
bsdd_search_classes (/api/Class/Search/v1) always covers IFC.
Class properties. The IncludeClassProperties option of /api/Class/v1 is deprecated and
heavily rate limited; bsdd_get_class_properties uses the dedicated paginated endpoint instead.
Page size. The API returns up to 1000 items per call. These tools default to 50 to keep
responses reasonable for a model context; pass limit explicitly when you need more.
npm run build # compile TypeScript to dist/
npm run typecheck # type-check only
npm test # build + unit tests (no network; fetch is stubbed)
npm run test:live # calls every tool against the real bSDD APIMIT — see LICENSE. bSDD content itself is published by buildingSMART International and
its dictionary owners under their own licenses (each dictionary reports its license field).
Get the details of one class: definition, class type, related IFC entities and (optionally) child classes and relations. Properties are fetched separately with bsdd_get_class_properties.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Class URI, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3/class/IfcWall". Use bsdd_search_classes to find one. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. | |
| includeClassRelations | No | Include the relations of this class. | |
| includeReverseRelations | No | Include relations pointing at this class from other classes. | |
| includeChildClassReferences | No | Include references to child classes. | |
| reverseRelationDictionaryUris | No | Restrict reverse relations to these dictionaries. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so safety is covered. The description adds value by stating that properties are excluded and listing what is included (definition, class type, related IFC entities), giving behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences. The first sentence states the purpose and scope with a clear verb and resource; the second sentence provides a necessary separation from a sibling tool. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description enumerates the returned contents (definition, class type, related IFC entities, optional child classes/relations) and notes the property separation. It is sufficiently complete for a get-details tool with good annotations, though it omits details about language fallback or error behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter is already described in the schema. The description does not add parameter-specific details; it focuses on the output scope. The baseline of 3 applies because the schema carries the parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Get the details of one class' and enumerates the specific content (definition, class type, related IFC entities, optionally child classes and relations). It also distinguishes itself from the sibling tool bsdd_get_class_properties by explicitly noting they are fetched separately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Properties are fetched separately with bsdd_get_class_properties,' providing a clear alternative and exclusion. It implies this tool should be used when class details other than properties are needed, though it does not mention the closely related bsdd_get_class_relations tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the properties assigned to a class, with their data type, units, allowed values and property set. Use this instead of the deprecated IncludeClassProperties option of bsdd_get_class.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| classUri | Yes | Class URI, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3/class/IfcWall". Use bsdd_search_classes to find one. | |
| searchText | No | Optional filter on property name, description or code. Cannot be combined with propertySet/propertyCode. | |
| propertySet | No | Optional filter on property set name. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. | |
| propertyCode | No | Optional filter on property code. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds that the response includes data type, units, allowed values, and property set, and clarifies the deprecation context. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and a direct alternative reference. Every word earns its place; no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description explains what is returned (properties, data type, units, allowed values, property set). It also notes the deprecation of an alternative. For a list tool with a well-documented schema, this is sufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with detailed descriptions for all 7 parameters, so the schema carries the heavy lifting. The description mentions output content (data type, units, allowed values) but adds no specific input parameter semantics beyond what the schema already provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and clearly identifies the resource: 'the properties assigned to a class'. It enumerates the included details (data type, units, allowed values, property set), and differentiates itself from the deprecated IncludeClassProperties option of bsdd_get_class.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Use this instead of the deprecated IncludeClassProperties option of bsdd_get_class', providing a direct alternative and when-to-use guidance. This clearly tells the agent when to select this tool over a sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the relations of a class (e.g. IsEqualTo, HasMaterial, IsParentOf) or, with reverse=true, the classes that point at it. Useful for mapping between dictionaries.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| reverse | No | Return reverse relations (classes relating to this class) instead of forward relations. Default false. | |
| classUri | Yes | Class URI, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3/class/IfcWall". Use bsdd_search_classes to find one. | |
| searchText | No | Optional filter on the related class name. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, idempotent, non-destructive behavior, so the low bar is met. The description adds value by explaining the semantics of reverse=true ('the classes that point at it') and giving relation type examples, which goes beyond what annotations alone convey. No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action, includes examples, and a use case. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 params and no output schema, but the schema documents each parameter thoroughly and annotations cover safety. The description covers purpose and use case, though it does not describe the return format or potential edge cases. For a read-only list operation, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the baseline is 3. The description adds marginal value by clarifying the reverse parameter's effect and showing example relation names, which helps an agent understand the domain. This slightly elevates it above the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('relations of a class'), provides concrete examples (IsEqualTo, HasMaterial, IsParentOf), and explains the reverse mode. This unambiguously distinguishes it from sibling tools like bsdd_get_class (single class) and bsdd_get_class_properties (properties).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case ('Useful for mapping between dictionaries') and implies when to use it by mentioning reverse mode. However, it does not explicitly state when NOT to use it or name alternative tools for direct comparison, so it stops short of full when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the details of one property: data type, units, allowed values, description and related properties.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Property URI, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3/prop/IsExternal". | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about the returned data fields, which is useful since there is no output schema. It does not discuss error behavior or language fallback beyond what the parameter description already states, but the annotation coverage lowers the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose and lists the key output details. Every word earns its place with no redundancy or unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get tool with only two parameters and strong annotation coverage, the description is fairly complete. It enumerates return content, which compensates for the lack of an output schema. However, it lacks usage guidance relative to siblings and does not mention potential errors or edge cases, so it is not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (uri and languageCode) already described meaningfully in the schema. The tool description adds no additional parameter semantics beyond the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets details of one property and enumerates exactly what fields are returned (data type, units, allowed values, description, related properties). This is a specific verb+resource definition and distinguishes it from sibling tools like bsdd_get_property_classes or bsdd_get_property_value.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use it (when you need details of a single property) but provides no explicit guidance on when not to use it or which sibling tool to choose instead. No alternatives are mentioned within the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the classes that use a given property.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| searchText | No | Optional filter on the class name. | |
| propertyUri | Yes | Property URI. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral context beyond what annotations provide, such as pagination or fallback behavior, but it does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately communicates the tool's purpose. Every word is meaningful, and the structure is front-loaded with the verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with a well-described schema and annotations covering safety, the description is sufficient. It lacks detail on return format or pagination behavior, but the schema's limit/offset parameters provide some of that context. A minor gap is not explaining what 'use' means semantically, but it is not necessary for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all five parameters having descriptive text. The description itself adds no extra parameter semantics beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('classes') with a clear scope ('that use a given property'). It distinguishes itself from reverse sibling tools like bsdd_get_class_properties, which lists properties for a class.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you have a property and need to find which classes reference it. It does not explicitly name alternatives or exclusions, but the context is clear from the sibling tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the details of a single property value (an item of an enumeration), by its URI.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | Yes | Property value URI. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false. The description adds useful context that it retrieves a single, enumeration item via URI, which goes beyond the annotations. No contradiction is present, and the added scope clarity justifies a score above baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tightly worded sentence that front-loads the verb and resource. Every word contributes to the meaning, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with two well-documented parameters and rich annotations, the description covers the essential purpose and identifier. No output schema exists, but the 'details' phrasing is sufficient given the straightforward nature of the operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for both 'uri' and 'languageCode'. The description only states 'by its URI', which mirrors the schema's property description and does not add new semantic meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly identifies the resource: 'details of a single property value (an item of an enumeration)'. It also specifies the lookup method 'by its URI', which distinguishes it from sibling tools like bsdd_get_property or bsdd_get_class_properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the agent has a URI for a property value, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The sibling list provides context, but the description itself does not leverage it to guide tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the dictionaries (classification systems, e.g. IFC, ETIM, Uniclass) published in bSDD. Start here to discover the dictionary URIs the other tools need.
| Name | Required | Description | Default |
|---|---|---|---|
| uri | No | Optional filter on the start of the URI. Leave the version off to get every version of a dictionary, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/". | |
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| includeTestDictionaries | No | Include test dictionaries. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, covering the safety and repeatability profile. The description adds no further behavioral details (e.g., pagination behavior or response structure), but for a simple list operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-crafted sentence that front-loads the main purpose and immediately provides the key usage context. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with optional filters and no output schema, the description adequately sets expectations about discovering dictionary URIs. It could mention what the response contains, but 'discover the dictionary URIs' implies the key output, making it sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter clearly documented (e.g., uri format with example, numeric ranges for limit/offset, defaults). The description adds no additional parameter context, but the schema carries the full burden effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List the dictionaries' with specific examples (IFC, ETIM, Uniclass). It distinguishes from sibling tools by targeting the top-level 'dictionaries' resource rather than classes or properties.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given with 'Start here to discover the dictionary URIs the other tools need.' This clearly indicates when to use the tool, though it doesn't explicitly mention alternative tools or scenarios to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the classes of one dictionary, optionally filtered by text, class type or related IFC entity. Use this to browse a dictionary; use bsdd_search_classes to search across dictionaries.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| classType | No | Optional filter on class type. | |
| searchText | No | Optional filter text. Ignored when useNestedClasses is true. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. | |
| dictionaryUri | Yes | Dictionary URI including version, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3". The version may be replaced by "latest". | |
| useNestedClasses | No | Return the classes as a tree instead of a flat list. Cannot be combined with pagination. | |
| relatedIfcEntities | No | Optional filter on related IFC entities, by code (e.g. "IfcWall", version-independent) or by class URI. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so the safety profile is clear. The description adds minimal behavioral context beyond this, such as the filtering options already present in the schema. No contradictions, but also no additional behavioral insights like pagination or tree structure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences front-load the core purpose and usage boundary. No wasted words; the description is compact and efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list operation with a detailed schema and safety annotations, the description is complete enough. It covers the core function and usage, though it does not describe the return format or pagination behavior—but these are not essential given the schema's parameter descriptions and the tool's straightforward nature.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% description coverage, so parameters are already well-documented. The description only summarizes the filter types ('text, class type or related IFC entity') without adding new semantic meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists classes of a single dictionary with optional filters, using a specific verb ('List') and resource ('classes of one dictionary'). It distinguishes itself from siblings by explicitly naming bsdd_search_classes for cross-dictionary searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides usage context: 'Use this to browse a dictionary; use bsdd_search_classes to search across dictionaries.' This clearly delineates when to use this tool versus the alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the properties defined by one dictionary, optionally filtered by text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| searchText | No | Optional filter text. | |
| languageCode | No | Language code, case sensitive (e.g. "EN", "nl-NL"). Falls back to the dictionary default language. | |
| dictionaryUri | Yes | Dictionary URI including version, e.g. "https://identifier.buildingsmart.org/uri/buildingsmart/ifc/4.3". The version may be replaced by "latest". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the operation is scoped to a single dictionary and supports filtering, but does not elaborate on pagination behavior or return format, which are partially covered by the schema parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that directly states the tool's purpose without redundant detail. It earns its place and is easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with comprehensive annotations and fully documented parameters, the description is sufficient. It clearly communicates the scope and optional filtering. It does not describe return values, but the tool name implies a list of properties, and the schema covers pagination parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for all five parameters (dictionaryUri, limit, offset, searchText, languageCode), so the description does not need to explain each. The mention of 'filtered by text' aligns with the searchText parameter but adds no new semantic information beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: listing properties defined by a single dictionary, with optional text filtering. This differentiates it from siblings like bsdd_list_dictionary_classes (which lists classes) and bsdd_get_class_properties (which retrieves properties for a class).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: to list properties within a specific dictionary, optionally filtered by text. It does not explicitly mention when not to use it or name alternatives, but the intended use case is unambiguous given the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List one of the bSDD reference lists: countries, languages, units (with QUDT URIs) or reference documents. These are the allowed values for the corresponding fields on classes and properties.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Which reference list to return. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the detail that units include QUDT URIs and that these are allowed field values, offering contextual behavior beyond the annotations, but doesn't disclose response format or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no superfluous information. The first sentence front-loads the action and resource, the second adds important context about usage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one simple parameter and no output schema, the description adequately conveys that the tool returns a reference list for a given kind. However, it doesn't specify the exact response format (e.g., array of code/name pairs), which could be helpful but isn't critical for this simple, read-only tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the 'kind' parameter with a full enum and description, so the baseline is 3. The description enhances this by naming the specific lists and noting that units include QUDT URIs, and by explaining that these are allowed values for class and property fields, adding meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' with a clear resource 'bSDD reference lists' and enumerates the exact lists (countries, languages, units, reference documents). This distinguishes it from sibling tools that list dictionaries or classes, as 'reference lists' is a distinct category.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that these lists are 'the allowed values for the corresponding fields on classes and properties,' providing clear context for when to use this tool. While it doesn't explicitly name alternatives or exclusions, the sibling tool names (e.g., list_dictionaries, list_dictionary_classes) and the reference to 'reference lists' imply this is for reference data rather than dictionary content.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search for classes across all bSDD dictionaries, including IFC. This is the best starting point for questions like "which class describes a wall?".
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| searchText | Yes | Text to search for in class names and codes. | |
| dictionaryUris | No | Optional list of dictionary URIs to restrict the search to. | |
| relatedIfcEntities | No | Optional filter on related IFC entities, by code (e.g. "IfcWall") or by class URI. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the description doesn't need to repeat that. It adds the scope of searching all dictionaries including IFC, but does not disclose return format or pagination behavior, which is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences long, front-loaded with the core purpose and an illustrative example, with no redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is read-only, has well-documented schema parameters, and has no output schema. The description adequately conveys scope and when to use it, though it could optionally mention what the response contains (class objects).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters, so the description adds no extra parameter semantics. The example usage is helpful but does not clarify parameter details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'search' with the resource 'classes across all bSDD dictionaries, including IFC' and gives a concrete example question, which clearly distinguishes it from sibling tools like bsdd_search_text.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states a clear usage context ('best starting point') but does not explicitly list when-not-to-use or mention alternative tools for property searches, so it earns 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Free-text search returning both classes and properties. Pagination is shared: classes are listed first, properties after them. Note that the IFC dictionary is only included when includePreview is true (the default here); use bsdd_search_classes for class-only searches.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of items to return (1-1000). Defaults to 50. | |
| offset | No | Zero-based offset of the first item returned. Default 0. | |
| searchText | Yes | Text to search for. | |
| typeFilter | No | Filter by type: "Class", "Property", "Material", "GroupOfProperties", or a semicolon separated list. | |
| onlyVerified | No | Only return results from verified dictionaries. | |
| dictionaryUris | No | Optional list of dictionary URIs to restrict the search to. | |
| includePreview | No | Include dictionaries in preview state. Defaults to true here, because IFC is one of them. | |
| includeInactive | No | Include inactive items. Default false. | |
| onlyLatestVersion | No | Only search the latest version of each dictionary. | |
| includeSearchDescriptions | No | Also search in descriptions. Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly, openWorld, idempotent), the description discloses shared pagination behavior ('classes are listed first, properties after them') and the IFC preview default, which are meaningful behavioral nuances. This adds substantial context that would not be obvious from the schema alone.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of three sentences, each delivering distinct information: purpose, pagination behavior, and an alternative tool with a default note. It is front-loaded and contains no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters and no output schema, the description covers the most important behavioral aspects: the combined result type, pagination, and IFC preview condition. It does not detail the return structure, but for a search tool the description is sufficiently complete to guide correct invocation and interpretation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds semantic value by explaining that includePreview defaults to true here and that this affects IFC dictionary inclusion, and by connecting the shared pagination to the semantics of limit/offset. This goes beyond merely restating parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Free-text search returning both classes and properties,' which clearly states the tool's purpose with a specific verb and resource. It also distinguishes itself from the sibling bsdd_search_classes by noting 'use bsdd_search_classes for class-only searches,' making the differentiation explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides direct usage guidance: it tells users to use bsdd_search_classes for class-only searches, and it clarifies the IFC dictionary inclusion condition with includePreview. This gives clear when-to-use and when-not-to-use instructions relative to the sibling tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource-action combination: list vs search vs get, and each resource (dictionaries, classes, properties, relations, reference data) has a single clear purpose. The search tools are differentiated by scope (classes-only vs classes+properties), and listing tools specify whether they are scoped to a dictionary.
All tools follow the bsdd_<verb>_<noun> pattern, with verbs limited to list, search, and get. The noun phrases are consistently compound structures (e.g., dictionary_classes, class_properties, property_value), making the naming predictable and uniform.
12 tools is well-scoped for a read-only dictionary API, covering the core entities (dictionaries, classes, properties, relations, reference data) without redundancy or fragmentation. Each tool earns its place.
The tool set provides comprehensive read access to bSDD: dictionary discovery, class/property browsing and search, detailed entity retrieval, relations, property values, and reference data. No significant gaps exist for the stated purpose of reading the dictionary.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read-only search of your Sortio knowledge graph (files and entities) for Claude and ChatGPT.
Search and query nTop's knowledge base and engineering guides from AI applications.
Search verified Claude Code plugins and skills; fetch portable SKILL.md sources. Read-only.
Versioned documentation registry and semantic search for AI tools and coding assistants.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nhantruong96/bsdd-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
