Bitbybit 3D parametric CAD API, version-exact, for coding agents: search, describe, examples, guide
Scored across 7 tools
search and search_api are heavily overlapping — both find API members by keywords and return dotted paths — and the descriptions do not clearly explain why an agent should pick one over the other. describe vs fetch is also somewhat fuzzy (contract detail vs full doc text), though their outputs are distinguishable. The remaining tools (get_guide, get_examples, list_namespace) have clear distinct roles.
There is a mix of bare verbs (describe, fetch, search) and prefixed forms (get_examples, get_guide, list_namespace, search_api). All are snake_case, which keeps it readable, but the pattern is not predictable — search vs search_api in particular breaks a single verb_noun convention.
Seven tools is well-scoped for a documentation/reference server covering discovery, contract lookup, full docs, examples, and guides. Each tool earns its place and the set is neither thin nor bloated.
The surface covers the full documentation lifecycle: discovery (list_namespace, search, search_api), detailed contract (describe), full reference text (fetch), examples, and guides. Minor gaps exist, e.g. no explicit way to check the API version the server holds or list available versions, which the descriptions imply is relevant.
The exact contract of one member by dotted path, for example occt.shapes.solid.createBox: signature, every parameter with its type, default and range, the return type, the documentation, examples and where it runs. Answers are for the API version the server holds. It also describes the types a member returns or takes by their name, for example Inputs.IFC.SpaceInfoDto, field by field, and a member's answer lists those types. An unknown path is reported as not found together with the nearest existing paths; nothing is guessed.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | The dotted path of the member, for example occt.shapes.solid.createBox, or the name of a type a member returns or takes, for example Inputs.IFC.SpaceInfoDto | |
| version | No | The API version to describe; omit for the version the server holds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real value beyond that: version-scoped answers, that type names (e.g. Inputs.IFC.SpaceInfoDto) are resolvable field by field, and that unknown paths fail with nearest-path suggestions rather than guessing.
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 core purpose and the example are front-loaded, and every sentence carries content (return fields, type resolution, version scope, error behavior). It is dense with run-on sentences and could be tightened, but there is little outright 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?
With no output schema, the description steps in to enumerate what a result contains: signature, per-parameter type/default/range, return type, docs, examples, and execution location. Combined with version and not-found behavior, an agent has enough to call it correctly; only the lack of any pointer to searching for paths keeps it from a 5.
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 both parameters are already documented, including the version default. The description echoes the path example and version semantics without adding format or syntax detail beyond the schema, so the baseline of 3 applies.
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?
States a specific verb (describe) and resource (one API member by dotted path), with a concrete example path. It is clearly distinguishable from siblings like search_api and fetch, which the agent would use to discover or retrieve rather than inspect a contract.
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?
Implied usage is clear from the requirement of an exact dotted path, and it helpfully notes that unknown paths return nearest matches. However, it never explicitly says when to prefer this over siblings such as search_api, fetch, or get_examples, leaving the routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches the full documentation of one Bitbybit API member by id (a dotted path returned by search) as text, with its title, url and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | A dotted API path returned by search |
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 useful behavioral detail beyond annotations by specifying that the result is full documentation as text, and that title, url, and metadata are included.
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?
A single, information-dense sentence that front-loads the action and resource, then provides the return shape. Every element earns its place with 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?
The tool has one parameter, clear annotations, and no output schema, so the description's disclosure of output type ('as text') and included components ('title, url and metadata') is sufficient for an agent to invoke it correctly. No critical operational detail is missing for this low-complexity fetch 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 coverage is 100%, so the schema already documents the only parameter adequately. The description briefly restates that the id is a dotted path from search, which adds no meaningful new semantics beyond the schema field description.
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 states a specific action ('Fetches the full documentation'), a precise resource ('one Bitbybit API member by id'), and the input provenance ('a dotted path returned by search'). It also includes the output form ('as text, with its title, url and metadata'), making the tool's purpose distinct from search/describe/example siblings.
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 the tool is for retrieving documentation for a known API member id obtained from search, which gives actionable usage context. It does not explicitly name sibling alternatives or state when not to use it, so it stops short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Working TypeScript examples for a member path, for a namespace, or for a topic given as keywords. Each example names the member it belongs to and links its reference page. Examples are written for the API version the server holds.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | A member or namespace path, for example occt.shapes.solid.createBox or occt.fillets | |
| limit | No | How many examples, 5 by default | |
| topic | No | Keywords to find examples by, when no path is known | |
| engine | No | Prefer members published for this engine when searching by topic | |
| version | No | The API version; omit for the version the server holds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: examples are working TypeScript, each names its member and links the reference page, and examples are tied to the server's API version. No contradiction 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?
Three short, purposeful sentences with no filler. The core purpose is front-loaded, followed by result characteristics and version behavior; every sentence earns its place.
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 description, combined with a rich schema and safety annotations, covers the lookup modes, result content, and version behavior well. It is nearly complete, though the exact response shape and interaction between multiple optional parameters are not fully specified.
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 the baseline is 3. The description adds only general mode framing and version behavior, while the schema already documents path, limit, topic, engine, and version in sufficient detail.
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 states that the tool returns working TypeScript examples for a member path, namespace, or topic keywords, and adds detail about result content and linked reference pages. It is specific and useful, though it does not explicitly distinguish itself from sibling tools like search, fetch, or describe.
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 indicates when to use the tool: when examples are needed for a member path, a namespace, or a topic given as keywords. It does not provide explicit exclusions or point to alternative sibling tools, so it stops short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sections of the public guides: building with Bitbybit (what runs in the browser, on a server, on a lightweight backend, and what needs CAD Cloud), writing geometry with the kernels (which kernel to use, the order to build a part in, choosing edges, checking and exporting shapes), writing design documents (parametric models as JSON: parameters, sketches, features, references, parts and assemblies), and writing IFC building models (storeys, walls and their joins, doors, windows, slabs, roofs, rooms, properties and quantities). Without a topic it lists the sections. Read "integrate" before recommending where geometry should run: the npm packages are the default, and CAD Cloud is for algorithms that exist only there or compute the caller cannot provide. Read "geometry" before writing geometry code, "design" before writing a design document, and "ifc" before writing an IFC model.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | A section id or a short name such as integrate, browser, backend, server-side, pro, start, geometry, part-order, geometry-mistakes, design, references, assembly, ifc, ifc-order, ifc-mistakes; omit to list the sections |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive/openWorld=false, so safety is covered. The description adds the key behavioral fact that omitting the topic lists sections rather than returning an error, which the annotations cannot express. It stops short of describing return format or content size.
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?
Front-loaded with the resource and topic catalog, then usage rules, with no filler or marketing language. It is dense and the topic catalog is long, but every clause maps a topic to its content, so the length is largely justified.
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 single optional-parameter, read-only lookup with no output schema, the description covers what is queried, the default no-topic behavior, and when to consult which section. The one omission is any indication of what the returned guide content looks like, which the absent output schema would otherwise require.
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% and the schema already enumerates valid topic ids, so the baseline is 3. The description goes further by explaining what each section actually contains (e.g., kernels, part-order, IFC storeys/walls/joins), which helps an agent pick the right topic rather than guess from names alone.
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 names the resource concretely (sections of the public guides) and enumerates the four content areas (integrate/building, geometry, design, ifc), so an agent knows exactly what this tool surfaces. It never names a sibling or states a verb for the tool itself ('Without a topic it lists the sections' is the closest), so it is clear but not fully differentiated from search/get_examples/fetch.
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?
Gives explicit when-to-use triggers: read 'integrate' before recommending where geometry should run, 'geometry' before writing geometry code, 'design' before writing a design document, 'ifc' before writing an IFC model. It also states the default behavior when no topic is supplied, so an agent knows both the precondition and the fallback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The members one level below a namespace path, for example occt.shapes, each with its kind and summary. Without a path, the top-level namespaces. Use it to discover what exists before searching for details.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | A namespace path such as occt or occt.shapes; omit for the top level | |
| version | No | The API version to list; omit for the version the server holds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnly, idempotent, and non-destructive hints. The description adds meaningful behavioral context beyond that: results are limited to one level (not recursive), the output includes kind and summary, and omitting the path defaults to top-level namespaces. This discloses scope and default behavior the annotations cannot express.
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 with zero waste: the core behavior is front-loaded, the example clarifies, and the usage guidance closes. Every sentence earns its place and there is no redundant 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 read-only, low-complexity tool with no output schema, the description covers the essentials: what is returned (members with kind and summary), the depth limit, the no-path default, and when to use it. Minor gaps remain, such as behavior on invalid paths or how version affects results, but nothing an agent needs to invoke it correctly is missing.
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 the parameters are already fully documented. The description's example 'occt.shapes' reinforces the path parameter's meaning but largely duplicates what the schema says ('A namespace path such as occt or occt.shapes'), adding no substantive new semantics. The version parameter is not mentioned in the description at all.
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 states a specific verb and resource: it lists 'the members one level below a namespace path' and gives a concrete example ('occt.shapes'). It also describes the result contents ('each with its kind and summary') and frames itself as a discovery tool distinct from the search/detail siblings.
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?
'Use it to discover what exists before searching for details' is a clear when-to-use directive that positions this tool ahead of the search siblings. However, it does not name the alternative tool explicitly or state a when-not-to-use condition, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Searches the Bitbybit API documentation and returns a list of results with id, title and url. Each id is a dotted API path that fetch accepts.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search terms |
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 the return format (id, title, url) and the semantic meaning of id, which is useful. It doesn't mention pagination or result limits, but the annotations carry the main behavioral 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?
Two sentences with no waste. The core action, return format, and the connection to fetch are all front-loaded and clearly stated.
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 search tool with one parameter and annotations covering safety, the description is nearly complete. It could mention result limits or pagination, but the connection to fetch and the return format are sufficient for an agent to use it 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%, so the schema already documents the query parameter. The description doesn't add much beyond what the schema provides, but it does clarify that the query is for searching documentation. 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 clearly states the tool searches the Bitbybit API documentation and returns a list of results with id, title, and url. It also explains that each id is a dotted API path that fetch accepts, which distinguishes it from other tools like search_api and describe.
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 for searching documentation and explicitly connects to fetch by explaining the id format. It doesn't explicitly state when not to use it or name alternatives, but the context is clear enough for an agent to select it for documentation search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Bitbybit API members (methods, namespaces, cloud operations) by keywords, for example "box solid" or "fillet edges". Returns dotted paths with a one-line summary, the tier (oss on npm, platform-pro only at bitbybit.dev, cloud-pro only on CAD Cloud) and the engines each is published for. Call describe with a path before writing code that uses it.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | How many results, 10 by default | |
| query | Yes | Keywords, a phrase, or a partial dotted path | |
| engine | No | Only members published for this engine, plus the cloud operations, which run on CAD Cloud rather than in an engine; omit for every engine | |
| version | No | The API version to search; omit for the version the server holds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds meaningful behavioral context by detailing the returned fields—dotted paths, one-line summary, tier, and engines—which is especially useful given there is no output schema.
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 with no wasted words. It front-loads the purpose and examples, then states the return format and the follow-up action, earning every sentence.
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?
Given four parameters, robust read-only annotations, and no output schema, the description covers the essentials: what to search, what results look like, and what to do next. It relies on the schema for parameter details, which is appropriate, and only omits minor guidance about alternative tools.
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 the schema already documents all four parameters. The description adds useful query examples ('box solid', 'fillet edges') but does not materially extend the meaning of limit, engine, or version 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 states a specific verb and resource: 'Find Bitbybit API members' by keywords, with concrete examples. It also defines the scope (methods, namespaces, cloud operations) and the return payload, making it easy to distinguish from broader siblings like 'search'.
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 clear context for when to use the tool: searching for API members before writing code, and it explicitly directs the caller to 'Call describe with a path before writing code that uses it.' It does not explicitly name alternatives to avoid, but the workflow guidance is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
describe1 field changedInput schema / properties / path / descriptionPrevious value: -"The dotted path of the member, for example occt.shapes.solid.createBox"New value: +"The dotted path of the member, for example occt.shapes.solid.createBox, or the name of a type a member returns or takes, for example Inputs.IFC.SpaceInfoDto"get_guide1 field changedInput schema / properties / topic / descriptionPrevious value: -"A section id or a short name such as integrate, browser, backend, server-side, pro, start; omit to list the sections"New value: +"A section id or a short name such as integrate, browser, backend, server-side, pro, start, geometry, part-order, geometry-mistakes, design, references, assembly, ifc, ifc-order, ifc-mistakes; omit to list the sections"describefetchget_examplesget_guidelist_namespacesearchsearch_apiParametric 3D CAD for AI agents: build print-ready parts, check them, export STL, 3MF or STEP.
Headless CAD engine & MCP server for 2D/3D drafting, solids, DXF/SVG export, and automation.
Design 3D-printable parts by chatting: create, edit, render and publish parametric forges.
Run 3D CAD operations, pipelines, parametric models and STEP conversions on CAD Cloud with a key
Add one secure layer between your agents and this server.