mazarbul

Overview Schema Source Related Servers Discussions Admin

definePredicate

Register a new predicate in the shared vocabulary, defining its kind, description, domain/range, aliases, and attribute schema; check existing predicates first to avoid synonyms.

Instructions

Register a new predicate in the shared predicates vocabulary — but first call introspect to check existing predicates (works_at, member_of, etc.) so you don't mint a synonym. Inputs: predicate (snake_case), kind (functional for at-most-one-live-value, non-functional for multiple concurrent values), description, and optional typing: subjectKinds/objectKinds (domain/range — the entity kinds allowed on each end), sameAs (external-vocabulary IRIs), and propertySchema (a JSON Schema for the relation's attributes). Domain/range and attribute constraints are advisory by default and enforced only when [ontology] strict_domain_range is enabled. The predicate is immediately queryable via introspect and usable in relate calls. Re-registering an existing predicate updates its kind, description, domain/range, sameAs, and propertySchema and returns status=updated. Returns E_VALIDATION if the predicate name or propertySchema is malformed.

Input Schema

Name	Required	Description
`kind`	Yes	functional = at most one live value per subject (e.g. works_at). non-functional = multiple concurrent values allowed (e.g. member_of).
`sameAs`	No	Optional alias IRIs mapping this predicate to external vocabularies, e.g. ["https://schema.org/worksFor", "wikidata:P108"].
`predicate`	Yes	Snake_case predicate identifier, e.g. works_at or member_of. Must be unique in the predicates vocabulary.
`description`	Yes	One-sentence human-readable explanation of what the predicate means.
`objectKinds`	No	Optional range constraint: entity kinds allowed as the object of this relation, e.g. ["organization"] for works_at. Omit to accept any kind.
`subjectKinds`	No	Optional domain constraint: entity kinds allowed as the subject of this relation, e.g. ["person"] for works_at. Omit to accept any kind (open-world default).
`propertySchema`	No	Optional JSON Schema (Draft 2020-12) constraining the relation's attributes map, e.g. require a string role. Validated against relation instances only when [ontology] strict_domain_range is enabled.

Output Schema

Name	Required	Description	Default
`status`	Yes	registered = new predicate written to the vocabulary; updated = existing predicate's kind, description, domain/range, sameAs, and propertySchema overwritten.
`predicate`	Yes	The registered predicate identifier.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 31, 2026

TDQS

A4.6/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 does most of it: it discloses that re-registering mutates kind/description/domain-range/sameAs/propertySchema and returns status=updated, that domain/range constraints are advisory unless [ontology] strict_domain_range is enabled, and that malformed input returns E_VALIDATION. The gap is scope/authorization — a 'shared' vocabulary mutation with no statement about who may register or whether it affects other teams.

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?

Front-loaded with purpose and the introspect prerequisite, then a compact parameter enumeration, then consequences and error behavior. Dense but nearly every clause is load-bearing; the parenthetical domain/range glosses are mildly redundant with the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter mutation with nested propertySchema, the description covers semantics, config-gated enforcement, upsert behavior, error conditions, and cross-tool workflow. An output schema exists, and it still flags the status=updated shape, so nothing essential is missing.

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 already 100%, so the 3 baseline is met by structured fields alone; the description adds a domain/range framing for subjectKinds/objectKinds and connects propertySchema to the relation's attributes map, plus notes the advisory-vs-enforced behavior of those constraints. It doesn't add format detail beyond the schema's examples, so it stops short of a 5.

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?

Opens with a specific verb+resource ('Register a new predicate in the shared predicates vocabulary') and immediately positions it against siblings: introspect for checking, relate for consuming. An agent can distinguish this from defineEntityKind or defineSchema 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States an explicit prerequisite workflow ('first call introspect to check existing predicates ... so you don't mint a synonym'), explains re-registration as an update path, and names where the result is used (queryable via introspect, usable in relate calls). No alternative tool is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.