A
licenseA
qualityA
maintenanceAI-native ontology engineering MCP server for OWL/RDF/SPARQL. Validate, query, diff, lint, version, and govern knowledge graphs via Oxigraph triple store.
42
479
MIT
Operational Ontology
by gura105
Explore, aggregate, traverse, and act on a unified operational-ontology domain of Customer, Order, Product, and Note objects exposed over MCP tools.
Search objects:
search_customer,search_order,search_product,search_notefilter by equality on each type's properties.Fetch by key:
get_customer,get_order,get_product,get_noteretrieve a single object by its primary key.Aggregate:
aggregate_customer,aggregate_order,aggregate_product,aggregate_notegroup by a property, count, and optionally sum a numeric field, computed at query time.Traverse links:
traverse_customer_orders,traverse_order_products,traverse_order_noteswalk one-to-many and many-to-many relationships forward or reverse.Perform gated writes:
cancel_order(refuses shipped orders),assign_order(for pending orders), andadd_order_note— all enforce business rules and return machine-readable refusals.Audit:
read_audit_logshows every applied and rejected action with actor and params (unscoped administrative view).Scope note: Reads are filtered by the model-attached visibility policy; the actor is self-declared with no authentication.
English | 日本語
Operational Ontology
An operational ontology is a shared domain model over other systems' data: objects and links for reading the business, and actions that enforce business rules, audit attempts, and write changes back to the systems of record.
A semantic layer lets you read your business. An operational ontology lets you run it.
This repository makes that definition runnable in a small TypeScript reference implementation. Palantir Foundry's Ontology is the pattern's starting point; this example isolates the ideas so you can read, fork, and adapt them. It is a learning resource, not a framework or an npm dependency.
Quickstart
Requires Node.js 24 or later and pnpm.
pnpm install
pnpm demo # physical data → integrate → index → read → write → refusal → write-back
pnpm test # verify the behaviorThe demo follows the accompanying article: a company acquires a competitor and inherits two legacy order systems with different schemas and status encodings. SQL and a small mapping integrate their data into one model. Run it to see:
links and aggregates answer questions across both systems;
cancelOrderrefuse a shipped order and write an allowed cancellation back to the original ERP;assignOrderandaddOrderNotestore state owned by the ontology, which survives re-indexing while source data refreshes;applied and rejected action attempts appear in the audit log.
https://github.com/user-attachments/assets/02bb8ca0-a476-4e33-b0ea-25c46c6e9dda
Related MCP server: ORMCP Server
Why define Operational Ontology?
Answering “How many unshipped orders does this customer have?” consistently requires a model for reading data in business terms. When an application or AI agent goes on to cancel an order, it also needs to check the operation's conditions, record the attempt, and deliver the change to the ERP that owns the record. Treating these responsibilities as part of a shared model is this repository's starting point.
The terms “semantic layer” and “ontology” alone do not tell us how much of that responsibility is included. Comparing nearby concepts by what they model and how they handle business operations makes the distinction clearer.
Concept or arrangement | What it primarily models | Relationship to business operations |
Semantic layer | The meaning of metrics, attributes, and aggregates | Answers data questions consistently. Operation conditions and write-back require additional design. |
Formal ontology / knowledge graph | Conceptual meaning, entities, and relationships | Represents meaning and relationships. Business rules and audit need to be designed alongside data updates. |
AI context layer | Meaning and background for answers and decisions | Supports an agent's understanding. Governance of the operations it executes requires additional design. |
CRUD API / API wrapper | Data access or individual operations | Where rules, audit, and write-back are enforced depends on each API's design. |
Operational ontology | Shared objects and links, plus actions carrying business rules | Makes operation conditions, audit, and write-back to authoritative sources part of the shared model's contract. |
These technologies can be combined. The arrangement we want to name is one where every consumer changes state through the same model, under the same business rules. We draw this arrangement from Foundry's Ontology and define it as Operational Ontology through the four properties below, so it can be discussed and implemented independently of a particular product.
The four properties
This repository uses operational ontology for a system with all four properties. They describe the pattern; storage engines, integration tools, and consistency mechanisms are implementation choices.
Semantic objects and links. Business entities and relationships are modeled explicitly over existing data owned by other systems.
Action-gated writes. Business decisions change state only through named actions. Every consumer uses that same API. Source re-indexing is a separate infrastructure operation.
Business rules at the action. Preconditions enforce domain invariants such as “a shipped order cannot be cancelled.” Violations produce machine-readable refusals, and both applied and rejected attempts are audited. Preconditions express business validity; access policies decide who may act.
Write-back to systems of record. Every piece of state has a declared owner, and changes to source-owned state propagate back to its owner through governed side effects. The pattern includes actual writes to source-owned state.
Ownership has three forms in the example:
source-backed: the ERP owns
Order.status; cancellation writes back to it.ontology-owned: the ontology owns the assignee and notes, which have no source columns.
derived: totals and counts are computed at query time and are never written.
The pattern in code
The model is a plain value containing object types, link types, and action types. Each definition has corresponding instances at runtime.
Definition (type) | Runtime instance |
Object type: | An individual order and its properties |
Link type: | A connection between a particular customer and order |
Action type: | One call attempting to cancel a particular order |
Edits describe the changes an action proposes to objects and links. The audit log records execution attempts and their outcomes, including application and refusal. Definitions live in code; instance state and execution records live in the store.
The model is data rather than classes so the information needed to describe an operation can be enumerated. The method signature in class Order { cancel() {} } alone does not expose parameter validation rules or preconditions. This implementation keeps that information in the definition value, so applications can share the model, inspect it at runtime, and generate MCP tools from it.
In this extract, the cancellation rule lives alongside the action's parameters and the edits it describes. The imports and complete model are in examples/orders/ontology.ts.
const objects = {
Customer: defineObject({
primaryKey: 'id',
properties: { id: z.string(), name: z.string(), region: z.string() },
}),
Order: defineObject({
primaryKey: 'id',
properties: {
id: z.string(),
status: z.enum(['pending', 'shipped', 'cancelled']),
total: z.number().int(), // minor units — money is not a float
assignee: z.string().nullable(),
},
owned: { assignee: null }, // the ontology's own state, declared
source: 'north.tbl_order ∪ south.SALES_ORDER', // physical data comes first
}),
}
const ontology = defineOntology({
name: 'orders',
objects,
links: {
customerOrders: defineLink({ from: 'Customer', to: 'Order', kind: 'one-to-many' }),
},
actions: {
cancelOrder: defineAction(objects, {
object: 'Order',
targetParam: 'orderId',
params: { orderId: z.string(), reason: z.string().min(1) },
preconditions: [
({ object }) => object.properties.status === 'shipped'
? reject('SHIPPED_ORDER_CANNOT_BE_CANCELLED', `order ${object.pk} has already shipped`)
: undefined,
],
effects: ({ object }) => [modify(object, { status: 'cancelled' })],
writeback: true,
}),
},
})Calling execute('cancelOrder', …) loads the target and checks the rule. For an allowed write, the runtime validates the edit plan, writes it back, then commits the local edits and audit entry. The effects function only describes changes; the adapter performs the external write.
For AI agents (MCP)
pnpm mcp # serve the same ontology over stdioThe server generates tools such as search_order, traverse_customer_orders, cancel_order, and read_audit_log from the model. An agent cancelling a shipped order receives SHIPPED_ORDER_CANNOT_BE_CANCELLED, just as a human caller does. Business rules live in the model, so the prompt does not have to enforce them.
The repository's MCP configuration connects the orders example. Session identity and tool input details are in the implementation notes.
https://github.com/user-attachments/assets/28327062-e09f-4103-943e-434a0e55b327
Reading the code
Start with the first three files; use the others to follow a particular part of the demo.
File | What to look for |
The business model: objects, relationships, ownership, and action rules. | |
A caller exercising reads, successful writes, refusals, and re-indexing. | |
The interpreter: follow | |
The definition helpers, instance shape, and model-derived TypeScript types. | |
How the two legacy schemas become one snapshot. | |
How an accepted change reaches its source, including refusal of a stale cancellation. | |
How the same model becomes the agent's tool surface. |
tests/ makes the behavior and typing expectations executable. The implementation notes explain API details, processing order, and edge cases.
Scope and declared behavior
This repository implements the middle layer. The demo supplies the surrounding applications and data integration.
State absent from the sources, such as assignees and notes, and the record of action attempts need to be kept in this layer. This implementation therefore owns a store for action edits and the audit log alongside the indexed source snapshots.
An implementation must declare choices that callers can observe. This one makes the following choices, also exposed as Runtime.declarations:
Concern | This implementation |
Ownership | Declared by |
Write-back failure | Write-back runs first. If the source refuses, no local edit commits. If the source succeeds and the local commit fails, the systems diverge and need reconciliation. |
Re-indexing | Source-backed state refreshes; ontology-owned state survives. A load that would orphan an owned edit is refused. |
Visibility | An object with no policy is visible to everyone. The actor is self-declared; there is no authentication. Audit reads are an unscoped administrative view. |
The runtime demonstrates the pattern with synchronous calls and SQLite. It includes no UI builder, pipeline framework, scalable indexing service, or general authorization system. The write gate is an API contract within the caller's process. These boundaries keep the implementation readable.
Creation is limited to ontology-owned objects; deletes, link properties, and composite keys are unsupported. The implementation notes document the remaining limits and API details. Published versions are in the release notes.
FAQ
Isn't this just CRUD with validation?
The parts are familiar; the configuration is not. Typical CRUD validation lives inside one application, on tables that application owns. Here the model sits on data other systems own, is shared by every consumer (UIs, scripts, agents), routes every business write through actions, audits every attempt, and writes accepted changes back to the systems of record. The closest existing description is a CQRS command layer extracted from the application and placed over someone else's data.
Isn't a knowledge graph writable too?
Yes, including conditional updates. It also has both a schema and instances. Operational Ontology adds action types (business operation definitions) and their instances (individual execution attempts). It brings named business operations, machine-readable refusals, an audit trail of attempts, and write-back to the systems of record into the model as one unit. The difference is not capability — all of this can be built on a triple store — but what the model defines and governs as first-class elements.
Why TypeScript definitions instead of YAML?
Because business rules are code, and rule-expression languages embedded in YAML tend to grow into ad-hoc rule engines. TypeScript object literals keep the model enumerable while the rules stay ordinary typed code. Structure as data, rules as functions.
Prior art
Palantir Foundry Ontology: the pattern's starting point; see its semantic/kinetic model, action types, and write-back webhooks.
DDD, CQRS, and event sourcing: related ideas for entities, commands, guarded changes, and logs. Here the domain model is shared across consumers and sits over other systems' data.
Earlier uses of the term: Vladimir Kozlov's definition essay and Foundry introduction, and FSTech's Operational Ontology Framework. This repository states its own meaning through the four properties and runnable example above.
MIT © gura105
Available Tools
19 toolsadd_order_noteB
File a triage note against an order. Writes are gated: if a business rule rejects this call, the error is machine-readable ({ code, message }) and the attempt is recorded in the audit log.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| author | Yes | ||
| noteId | Yes | ||
| orderId | Yes |
TDQS
B3.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and discloses important behavioral traits: writes are gated by business rules, errors are machine-readable with a { code, message } shape, and attempts are audit-logged. It stops short of describing success responses or permission requirements, but adds meaningful safety and error context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core action, and every clause earns its place by adding error behavior and audit context. No fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a write operation with no annotations and no output schema, the description should compensate by explaining params and success behavior. It covers error handling but leaves essential invocation details undocumented, making the tool only partially self-explanatory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain any of the four required parameters (orderId, noteId, text, author). The schema only provides types and minLength, leaving the agent without semantic meaning for any field.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses a specific verb 'File' and identifies the resource 'triage note against an order', clearly distinguishing it from sibling tools like cancel_order or get_note. The purpose is immediately understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as search_note or read_audit_log. The description implies its use when adding a note to an order but does not state exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
aggregate_customerA
Group Customer objects by a property, counting each group and optionally summing a numeric property. Query-time aggregation — nothing is precomputed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| group_by | Yes |
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds the key behavioral insight that 'nothing is precomputed', but it does not explicitly state that the operation is read-only or describe what happens with filters. Since no annotations are provided, the description carries this burden, but it is only partially met.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no fluff. It communicates the core action and a critical behavioral trait efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description is incomplete. It does not specify the return format or how the optional sum is configured, and it does not explain the role of the filter parameter. The description covers the basic grouping idea but leaves significant operational details ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate for parameter meaning. It explains that grouping is done 'by a property', but the 'optionally summing a numeric property' feature has no corresponding parameter in the schema, leaving agents confused about how to invoke it. The description adds minimal value for the existing parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Group' with the resource 'Customer objects', and specifies the actions 'counting each group' and 'optionally summing a numeric property'. This distinguishes it from sibling search/get tools and other aggregate tools by explicitly scoping to Customer objects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for aggregating customer data and notes 'Query-time aggregation', but it does not explicitly state when to use this versus search_customer or other aggregate tools, nor does it mention alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
aggregate_noteB
Group Note objects by a property, counting each group and optionally summing a numeric property. Query-time aggregation — nothing is precomputed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | ||
| group_by | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the transparency burden. It discloses the query-time nature and counting/summing behavior, but leaves return format and the numeric property trigger unspecified, and omits read-only/safety details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with the scope and resource stated immediately. The additional 'query-time' clause provides useful context without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no documentation of the filter parameter or grouping output shape, the description is incomplete. The ambiguous 'summing a numeric property' is especially problematic for an agent needing to invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only vaguely references 'a property' for group_by and omits the filter parameter entirely. The mention of 'optional summing a numeric property' introduces a capability not reflected in the schema, misleading the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs 'Group' and 'counting' to state the aggregation operation on Note objects. It clearly distinguishes from sibling search/get/traverse tools by targeting aggregation specifically.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through the aggregation purpose but does not explicitly name alternatives or exclusions. The 'Query-time aggregation' clause hints at a differentiation from precomputed data, but there is no direct when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
aggregate_orderA
Group Order objects by a property, counting each group and optionally summing a numeric property. Query-time aggregation — nothing is precomputed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sum | No | ||
| filter | No | ||
| group_by | Yes |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It adds one useful trait ('Query-time aggregation — nothing is precomputed'), but it does not state whether the operation is read-only, describe the response format, mention performance considerations, or note any required permissions. This gives some transparency but not enough for a 4.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core action ('Group Order objects by a property'), and the second sentence adds a distinct behavioral note about query-time computation. 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has three parameters including a nested filter object and no output schema. The description covers the core grouping and summing behavior but gives no guidance on how to use the filter or what the result structure looks like. While adequate for a basic sense of the tool, it leaves gaps for an agent aiming to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the conceptual meaning of grouping and summing, but it omits the 'filter' parameter entirely and does not enumerate which property values are valid for group_by beyond what the schema enums already provide. This is only partial compensation for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Group') and resource ('Order objects'), clearly distinguishing this aggregation tool from sibling search/get tools. It further specifies the output behavior (counting each group, optionally summing a numeric property), making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states this is a query-time aggregation and that nothing is precomputed, implying it should be used when live aggregated data is needed. However, it does not explicitly name alternative tools (like search_order or get_order) or provide exclusion criteria, so it falls short of fully explicit 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.
aggregate_productA
Group Product objects by a property, counting each group and optionally summing a numeric property. Query-time aggregation — nothing is precomputed.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sum | No | ||
| filter | No | ||
| group_by | Yes |
TDQS
A3.9/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the transparency burden. It adds a meaningful behavioral detail: 'Query-time aggregation — nothing is precomputed' implies real-time results. However, it does not disclose other aspects such as read-only nature, performance implications, or output constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the main action and optional modifier. No filler or repetitive information; every word contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with a nested filter object, no output schema, and no annotations, the description gives a general sense of the output (group counts and optional sum) but omits filter semantics and result format details. It is adequate for the core aggregation but lacks completeness for advanced usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains the role of group_by ('by a property') and sum ('summing a numeric property'), which complements the schema's enums. But it does not mention the filter parameter at all, leaving that aspect to the schema. Since schema description coverage is 0%, the description only partially compensates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb+resource: 'Group Product objects by a property' and explains the counting and optional summing. This uniquely identifies the tool's function and distinguishes it from similar tools targeting other resources like Customer, Order, or Note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates the core use case: query-time aggregation for grouping/counting/summing. It does not explicitly exclude cases or compare with search_product or other aggregate tools, but the resource-specific wording makes when to use it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
assign_orderA
Assign a pending order to a person for fulfilment. Writes are gated: if a business rule rejects this call, the error is machine-readable ({ code, message }) and the attempt is recorded in the audit log.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| orderId | Yes | ||
| assignee | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description takes on the transparency burden. It discloses that writes are gated by business rules, that rejections return a machine-readable error object ({ code, message }), and that attempts are recorded in the audit log. This adds meaningful behavioral context beyond a mere 'assign' statement, though it stops short of detailing all side effects (e.g., order status change) or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and contains no filler. Every sentence adds value: the first identifies what the tool does; the second explains write gating and error behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter mutation tool with no output schema, the description covers the essential parts: the operation, the pending-order constraint, and error/audit behavior. It does not explain the success return value or permissions, but these gaps are less critical given the simplicity of the tool and the existing details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero description coverage (0%), so the description must compensate. It only paraphrases the parameters: 'pending order' implies orderId, and 'person' implies assignee, but it does not explain the expected format of assignee (e.g., user ID, email) or any other constraints beyond the schema's minLength:1. This is insufficient for full parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Assign'), the target ('a pending order'), and the recipient ('a person for fulfilment'). It is distinct from sibling tools like cancel_order, get_order, and search_order, which perform different operations on orders.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description specifies the usage context: assigning a pending order to a person for fulfilment. It does not explicitly mention when not to use it or compare to alternatives, but the context is clear enough for an agent to identify this as the correct tool for assignment operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
cancel_orderA
Cancel an order. Shipped orders cannot be cancelled. Writes are gated: if a business rule rejects this call, the error is machine-readable ({ code, message }) and the attempt is recorded in the audit log.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| reason | Yes | ||
| orderId | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses important behaviors: writes are gated, errors are machine-readable with code and message, and attempts are audited. It also notes the shipped-order restriction, though it omits what happens on success (e.g., resulting order status) or whether cancellation is reversible.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the main action, and every phrase contributes value. The gating and audit information is concise and packed with necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and output schema, the description covers the essential behavior, an exception, error format, and audit trail. It stops short of describing the success response or the effect on the order, but for a cancellation tool this is quite complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only implicitly references orderId via 'Cancel an order' and does not explain 'reason' at all. The purpose of the reason parameter is left entirely to inference, and its format or validation is not mentioned.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Cancel' with a clear resource 'order', and immediately adds a key constraint ('Shipped orders cannot be cancelled'), making the tool's purpose unambiguous and distinct from sibling tools like assign_order or add_order_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit when-not condition for shipped orders, which helps agents avoid misuse. It does not name alternative tools, but the cancellation action is unique among siblings, and the gated-write behavior implies that business rules will be checked.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_customerA
Fetch a single Customer by primary key (id).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
TDQS
A3.8/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does not disclose behavior such as what happens when the ID is not found (e.g., null vs error), authentication requirements, or return format. The description only restates the basic fetch operation without adding behavioral context beyond what the name and schema imply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the verb and resource. Every word contributes, with no redundant details or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-record fetch with one parameter, the description adequately explains what the tool does. The lack of output schema and annotations is mitigated by the simple nature of the tool, though it could benefit from noting not-found behavior or return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, but the description compensates by clarifying that 'id' is the primary key. This adds meaningful semantic context to the otherwise bare string parameter, though it does not detail format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Fetch', the resource 'Customer', and the method 'by primary key (id)'. This distinguishes it from sibling tools like search_customer and aggregate_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have a specific customer ID and need a single record, but it does not explicitly state when to use this over alternatives like search_customer. No exclusions or comparison to siblings are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_noteA
Fetch a single Note by primary key (id).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It conveys a read-only fetch action, which is transparent, but does not disclose behavior for missing ids (e.g., error or null) or any other side effects. It adds no extra behavioral traits beyond the basic operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the action, resource, and lookup method.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter and no output schema, the description is sufficiently complete. It covers the action and key identifier, though it omits error handling details. Given the low complexity, this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the schema only defines 'id' as a string. The description adds that 'id' is the primary key, which is a small semantic addition. However, it does not provide format, examples, or constraints, leaving room for ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a single Note by its primary key (id). It uses a specific verb ('Fetch'), specifies the resource ('a single Note'), and defines the lookup method ('by primary key'), distinguishing it from search or aggregate alternatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: when you have a specific id and need exactly one Note. However, it does not explicitly mention when not to use it or name alternatives like search_note, even though sibling tools exist. The context is clear but lacks explicit exclusions or alternative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_orderA
Fetch a single Order by primary key (id).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that this is a read-only fetch operation via the verb 'Fetch' and that it returns a single Order. However, it does not mention error handling, authentication requirements, or the structure of the returned object, leaving notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the verb and purpose. There is no waste, and every word contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of a get-by-id operation, the description covers the core behavior well. However, the lack of an output schema or error behavior leaves some ambiguity about what is returned when the id is valid or not found. Still, it is reasonably complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides only a bare 'id' string with no description, so the description compensates by clarifying that 'id' is the primary key of the Order. This adds semantic meaning beyond the schema, though it does not provide details on format or constraints. For a single parameter, this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Fetch' with the resource 'Order' and explicitly states 'by primary key (id)', which clearly defines the type of access. This distinguishes it from siblings like search_order, which searches rather than fetches by exact id.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by primary key (id)' gives clear context that this tool should be used when the exact id is known. It does not explicitly name alternatives or exclusions, but the purpose clarity implies the appropriate use case without ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_productB
Fetch a single Product by primary key (id).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It indicates a read operation through 'Fetch' but gives no details on error behavior (e.g., missing id), return structure, or whether the product exists. This is minimal behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly communicates the tool's purpose without any filler. Every word contributes to understanding what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id tool with one parameter and no output schema, the description covers the core function adequately. However, without annotations or output schema, it leaves the return shape and not-found behavior unspecified, making it minimally complete but not fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds the semantic meaning that 'id' is the primary key, which is not present in the schema's raw type definition. It does not provide formats, examples, or related lookup guidance, so it only partially compensates for the schema's lack of descriptive detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Fetch' and clearly identifies the resource ('a single Product') and the lookup mechanism ('by primary key (id)'). This distinguishes it from sibling tools like search_product (searching) and aggregate_product (aggregation), as well as from get_order/get_customer/get_note by naming the resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention search_product for filtered lookups or clarify that this tool requires a known primary key. Usage context is only implied by the wording, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
read_audit_logA
Read the append-only audit log: every applied and rejected action, with actor and params. This is an unscoped administrative view — entries are not filtered by visibility (fail-open, declared).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | No | ||
| status | No | ||
| target | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that the log is append-only (immutability), contains both applied and rejected actions with actor/params, and is explicitly fail-open and unscoped, which are critical behavioral traits. This is strong transparency, though it omits concerns like pagination or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the main purpose, then a key caveat. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives a good high-level overview but lacks details on filter semantics, return structure, and access controls. Given the absence of an output schema and annotations, these gaps reduce its completeness, though the tool is relatively simple.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of the 'action' or 'target' parameters or how they interact with the log. Only 'status' is partially clarified by the phrase 'applied and rejected'. This is insufficient compensation for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Read the append-only audit log: every applied and rejected action, with actor and params', which clearly identifies the tool's function and distinguishes it from sibling tools focused on orders, customers, and products. The 'unscoped administrative view' phrase further clarifies its role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description communicates that this is an unscoped administrative view, implying it is for admin-level audit use where visibility filters are bypassed. However, it does not explicitly name alternative tools 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.
search_customerB
Search Customer objects (A customer of the merged company). All filter fields are optional and match by equality. Results are scoped by the model-attached visibility policy for this session.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| name | No | ||
| region | No |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden. It discloses useful behavioral traits: 'All filter fields are optional and match by equality' and results are 'scoped by the model-attached visibility policy'. However, it does not describe the return format, pagination, or behavior when no filters are supplied, leaving gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences with no unnecessary words. The action and resource are front-loaded, and the behavioral details are efficiently conveyed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with three optional parameters and no output schema, the description covers the key semantics: optional equality filters and visibility scoping. It does not explicitly state that it returns a list of Customer objects, but the verb 'Search' implies a list. Given the low complexity, it is fairly complete, though explicit mention of the return structure would improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The statement that all filter fields are optional and match by equality adds meaning beyond the bare property names. However, it does not elaborate on each field beyond its name, and no additional details like allowed formats or examples are provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Search') and the resource ('Customer objects'), and adds context that a customer is 'of the merged company'. It clearly differentiates from other search tools by resource name, but does not explicitly contrast with siblings such as get_customer or aggregate_customer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given about when to use this search tool versus alternatives like get_customer or aggregate_customer. The only usage-related information is about filter optionality and equality matching, which pertains to parameter usage, not tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_noteA
Search Note objects (A triage note — state no source system has a table for). All filter fields are optional and match by equality. Results are scoped by the model-attached visibility policy for this session.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| text | No | ||
| author | No |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and provides useful behavioral details: filters match by equality, all fields are optional, and results are scoped by the visibility policy. This goes beyond a bare 'Search' statement, though it does not cover return format or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences with no fluff. The first defines the resource, the second explains filter behavior, and the third discloses visibility scoping. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description covers purpose, resource definition, filter semantics, and security scoping. It does not mention return type or pagination, but for a simple search with three optional string filters, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and parameters are described only by name (id, text, author). The description adds that all filters are equality-based and optional, which is useful but generic. Field-specific semantics are not expanded upon, though property names are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches Note objects and defines what a Note is ('A triage note — state no source system has a table for'), distinguishing it from siblings like get_note or aggregate_note. The verb 'Search' is specific and matches the tool's name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through 'All filter fields are optional' but does not explicitly state when to use search_note versus alternatives such as get_note for fetching by ID. No exclusions or alternative tools are mentioned, so guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_orderA
Search Order objects (A sales order, unified across both legacy systems). All filter fields are optional and match by equality. Results are scoped by the model-attached visibility policy for this session.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| total | No | ||
| status | No | ||
| assignee | No | ||
| sourceId | No | ||
| sourceSystem | No |
TDQS
A3.8/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses that filter fields match by equality and that results are scoped by a visibility policy—both non-obvious behaviors. It does not explicitly state read-only status, but 'Search' implies a non-mutating operation. This is good but not complete, as it omits potential details like pagination or result shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose. It uses three short sentences that each add value: purpose, filter behavior, and visibility scoping. No redundant or fluff content appears.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema and no annotations, the description covers essential aspects: what is searched, how filters work, and a crucial session-scoping detail. It does not mention return format or pagination, but the tool name and typical search semantics make these less critical. Given the low complexity of the parameters, this is reasonably complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. The statement 'All filter fields are optional and match by equality' adds meaningful behavior about how parameters work. However, it does not explain the semantics of individual fields beyond their names, leaving the agent to infer meaning. This is adequate but not thorough.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
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+resource: 'Search Order objects'. The parenthetical 'A sales order, unified across both legacy systems' adds valuable context that distinguishes it from other order-related tools like get_order. This is a precise and unambiguous purpose statement.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternative search/get tools. There is no mention of alternatives like get_order for fetching a single order, or any scenario-based recommendations. The only usage-related information is that filters are optional and equality-based, which is more about parameter behavior than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_productA
Search Product objects (An item from the ERP item master). All filter fields are optional and match by equality. Results are scoped by the model-attached visibility policy for this session.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | ||
| name | No | ||
| stock | No |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses important behavioral details: results are scoped by the model-attached visibility policy, and filters match by equality. However, it doesn't mention potential limits, ordering, or return format, which would improve transparency for a search operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loaded with the core purpose, and every sentence adds value. It avoids repetition and is appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with three optional filters and no output schema, this description provides the essential information: what it searches, how filters work, and session scoping. It doesn't explain pagination or result limits, but these are not necessarily critical for this tool's usage. Overall, it is sufficiently complete for most use cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has three parameters (id, name, stock) with no individual descriptions, so the description's statement that all filters are optional and match by equality adds meaningful collective semantics. It does not, however, provide per-parameter details beyond types already in the schema, so overall parameter guidance is moderate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for Product objects from the ERP item master, using a specific verb ('Search') and resource ('Product objects'). While it doesn't explicitly differentiate from sibling tools like get_product or aggregate_product, the name and scope make its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that all filter fields are optional and match by equality, giving clear context on how to use the search. However, it does not provide explicit guidance on when to choose this tool over alternatives like get_product (for single fetch) or aggregate_product (for analytics), so usage guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traverse_customer_ordersA
Traverse the Customer → Order link "customerOrders" (one-to-many). Pass an instance returned by get or search; its properties are a snapshot, not authority. Direction is inferred from source.type; an explicit direction must agree.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| direction | No |
TDQS
A4.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses that the instance's properties are a snapshot and not authoritative, and that direction is inferred from source.type. It omits other behavioral facts an agent would want: what the traversal returns, whether it re-reads current state, and any pagination or permission behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences with no filler; the link identity and cardinality are front-loaded, followed by the input provenance and the direction rule.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, and the description never states what a traversal yields (presumably a list of related Orders) or its size/pagination behavior. It adequately covers inputs and direction semantics but leaves the return side underspecified for a nested-object tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it does: it explains the origin of `source` (from get/search), that its properties are a snapshot, and the direction-inference rule plus the constraint that an explicit direction must agree with source.type. This is substantive meaning the schema does not encode.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (traverse) and a precisely named resource (the Customer → Order link "customerOrders"), including its one-to-many cardinality. An agent can distinguish this from sibling traversal tools like traverse_order_products or traverse_order_notes without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tells the agent where the required `source` must come from (an instance returned by get or search) and how direction is resolved. It does not explicitly contrast with get_order/search_order alternatives, 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.
traverse_order_notesA
Traverse the Order → Note link "orderNotes" (one-to-many). Pass an instance returned by get or search; its properties are a snapshot, not authority. Direction is inferred from source.type; an explicit direction must agree.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| direction | No |
TDQS
A4.1/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the behavioral burden. It does add a meaningful caveat that source properties are a snapshot and not authority, which is genuinely useful for an agent. But it doesn't disclose whether any data is mutated, authorization constraints, pagination of the one-to-many result, or what the traversal returns. Given no annotations, more behavioral disclosure is warranted, so a 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short clauses, no wasted words, and the key constraint (snapshot not authority) is front-loaded. Slightly elliptical but efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter traversal tool with no output schema and no annotations, the description is nearly complete: it explains the link, the source requirement, the snapshot caveat, and direction resolution. The one missing element is what the one-to-many traversal actually returns (a list of Notes) and whether it paginates, which would help an agent use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description is the only place meaning is added. It explains that 'source' must be a full instance (with type/pk/properties), that its properties are a non-authoritative snapshot, and that 'direction' is inferred from source.type unless explicitly provided. This covers the critical semantic for both parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (traverse) and resource (the Order→Note link 'orderNotes'), explicitly calls out the one-to-many cardinality, and distinguishes itself from sibling traversal tools by naming the link. An agent can differentiate it from traverse_customer_orders or traverse_order_products immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Tells the agent to pass an instance returned by get or search, which is a clear usage precondition. Direction inference rules are also stated. However, it doesn't mention when to prefer this over get/aggregate siblings or any exclusions, keeping it short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
traverse_order_productsA
Traverse the Order → Product link "orderProducts" (many-to-many). Pass an instance returned by get or search; its properties are a snapshot, not authority. Direction is inferred from source.type; an explicit direction must agree.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| direction | No |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations the description carries the full burden, and it does add real behavior: the passed properties are a snapshot, not authoritative, and direction is inferred from source.type with explicit direction required to agree. It still omits whether the operation is read-only, what it returns, and pagination/limits for a many-to-many traversal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the relationship and its cardinality. Slightly dense and abbreviation-heavy, but no sentence is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The input side is well covered, but with no output schema and no statement of what a traversal returns (related Product or Order instances, counts, pagination), the description leaves the agent guessing about results for a nested, many-to-many operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does: 'source' must be an instance from get/search and its properties are snapshot-only, while 'direction' is normally derived from source.type and must agree if supplied. It adds meaning well beyond the bare enum, though it doesn't explain direction values themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb (traverse), the exact relationship ('orderProducts', many-to-many) and its endpoints, which cleanly separates it from siblings like traverse_customer_orders and traverse_order_notes. An agent can identify the operation without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
States the prerequisite clearly ('Pass an instance returned by get or search'), which tells the agent what to feed it. It does not state when to prefer this over alternatives such as search_product, but the traversal-vs-search distinction is reasonably implied by the tool name and the snapshot caveat.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.4.0- Changed
traverse_customer_orders4 fields changed- removed
Input schema / properties / direction / defaultRemoved value: -"forward" - removed
Input schema / properties / pkRemoved value: -{ - "type": "string" -} - added
Input schema / properties / sourceAdded value: +{ + "properties": { + "pk": { + "type": "string" + }, + "properties": { + "additionalProperties": {}, + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "type": { + "enum": [ + "Customer", + "Order" + ], + "type": "string" + } + }, + "required": [ + "type", + "pk", + "properties" + ], + "type": "object" +} - changed
Input schema / requiredPrevious value: -[ - "pk" -]New value: +[ + "source" +]
- Changed
traverse_order_notes4 fields changed- removed
Input schema / properties / direction / defaultRemoved value: -"forward" - removed
Input schema / properties / pkRemoved value: -{ - "type": "string" -} - added
Input schema / properties / sourceAdded value: +{ + "properties": { + "pk": { + "type": "string" + }, + "properties": { + "additionalProperties": {}, + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "type": { + "enum": [ + "Order", + "Note" + ], + "type": "string" + } + }, + "required": [ + "type", + "pk", + "properties" + ], + "type": "object" +} - changed
Input schema / requiredPrevious value: -[ - "pk" -]New value: +[ + "source" +]
- Changed
traverse_order_products4 fields changed- removed
Input schema / properties / direction / defaultRemoved value: -"forward" - removed
Input schema / properties / pkRemoved value: -{ - "type": "string" -} - added
Input schema / properties / sourceAdded value: +{ + "properties": { + "pk": { + "type": "string" + }, + "properties": { + "additionalProperties": {}, + "propertyNames": { + "type": "string" + }, + "type": "object" + }, + "type": { + "enum": [ + "Order", + "Product" + ], + "type": "string" + } + }, + "required": [ + "type", + "pk", + "properties" + ], + "type": "object" +} - changed
Input schema / requiredPrevious value: -[ - "pk" -]New value: +[ + "source" +]
19 tool updates
v0.1.0- First observed
add_order_note - First observed
aggregate_customer - First observed
aggregate_note - First observed
aggregate_order - First observed
aggregate_product - First observed
assign_order - First observed
cancel_order - First observed
get_customer - First observed
get_note - First observed
get_order - First observed
get_product - First observed
read_audit_log - First observed
search_customer - First observed
search_note - First observed
search_order - First observed
search_product - First observed
traverse_customer_orders - First observed
traverse_order_notes - First observed
traverse_order_products
TDQS
A3.9/5.0
Scored across 19 tools
Disambiguation5/5
Each entity gets a clean search/get/aggregate triad with clearly different semantics (filtered multi-result, single fetch by id, grouped counts). Traversals are distinctly named per link (traverse_customer_orders, traverse_order_products, traverse_order_notes), and the write actions (add_order_note, assign_order, cancel_order) plus read_audit_log have no overlap with the read tools.
Naming Consistency5/5
Strict verb_noun snake_case throughout: search_/get_/aggregate_ prefixes repeat identically across all four entities, traverse_ is used uniformly for link walks, and write/administrative tools follow the same lowercase verb_noun form. No mixing of conventions.
Tool Count4/5
19 tools is on the higher side but each earns its place: a symmetric read/aggregate surface over four entities, three graph traversals, and three gated writes plus an audit reader. Nothing feels redundant, though the count sits at the upper boundary of comfortable.
Completeness4/5
Read coverage is complete and symmetric (search/get/aggregate for Customer, Order, Product, Note) with traversals across the main links and order lifecycle writes (assign, cancel, add note) plus auditing. Gaps are minor and arguably intentional: no create/update/delete for the mirrored entities, and no direct note-creation beyond add_order_note.
Maintenance
ActivityActive
ResponsivenessResponsive
Related MCP Connectors
Data-ontology maps of your business systems, served to AI agents over MCP.
Build multi-tenant apps over MCP. Schemas, CRUD, deploys — access control enforced server-side.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceORMCP Server is a database-agnostic MCP server that exposes relational databases as governed business objects (Customers, Orders, Products) for AI agents via ORM abstraction — instead of raw SQL or schema access. Works with any JDBC-compliant database (PostgreSQL, MySQL, Oracle, SQL Server, SQLite, and more). Reduces LLM token consumption by 60-70% through semantic data abstraction.6-
- FlicenseNot gradedqualityBmaintenanceDemo MCP server that exposes order and customer data as read-only tools for AI assistants, simulating a business API or internal data source.-
- AlicenseNot gradedqualityAmaintenanceCLI + 46-tool MCP server for the Orion declarative services runtime — build and operate REST/Kafka services, manage workflows, channels, connectors, traces, and backups.5Apache 2.0