Agent Master Data

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavior: it is a paid x402 call with a specific price ID, and it returns explainable issues, severity, affected fields, policy rules and remediation guidance. Cost and return-shape disclosure go well beyond the annotation set; only the failure mode for an unknown record_id is left unspecified.

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 tight sentences: cost model and identity first, then the assessed dimensions, then the return contract. No restatement of the title and no 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?

No output schema exists, yet the description characterizes the return payload (issues, severity, fields, policy rules, remediation) and confirms non-mutation, which is what an agent needs before spending a paid call. The gap is edge-case behavior for a nonexistent record_id and how partial dimensions affect results.

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 80%, so the enum domains and the record_id/attributes exclusivity are already documented in the schema. The description restates the either/or input mode but adds no syntax, format, or size guidance beyond what the schema carries, so the baseline 3 is right.

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?

Names a specific verb (assess) plus the exact resource and dimension scope, and distinguishes the two input modes (existing golden record vs supplied attributes). It never names a sibling tool, so an agent must infer that this is the assessment operation versus the get_*/search_* family.

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 leading 'Paid x402 tool' caveat and 'without changing data' frame when this is appropriate (a costed, non-mutating check), and the attribute-vs-record duality is implied. However there is no explicit when-to-use/when-not-to-use statement and no pointer to alternatives such as get_master_data_golden_record if the caller only wants to read the record.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely new context: it is a paid x402 tool with a concrete price ID, and it enumerates the returned payload (identifiers, lineage, survivorship, freshness, relationships, quality) — valuable because 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?

Three tight sentences, front-loaded with the payment model and the core action, then the return inventory. Nothing repeats the title or wastes a clause.

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 2-param read tool with no output schema, the description successfully compensates by listing the return contents and disclosing the paid/x402 pricing. Minor gaps remain: not-found behavior, cost magnitude, and whether payment is per-call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 50% schema description coverage, the schema already documents record_id and the entity_type enum. The description only echoes 'stable record ID' and adds no format, expected ID shape, or domain-specific caveat for either parameter, so it barely improves on the structured fields.

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 and resource – retrieve one authoritative public golden record by stable record ID – and enumerates what is returned, so the agent knows exactly what it gets. It never names a sibling (search_master_data, resolve_master_data_entity) to contrast against, so differentiation is left to inference.

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?

No explicit when-to-use, when-not-to-use, or alternative routing appears in the description; the only sibling routing hint ('reference data is served by get_reference_data') lives in the schema's enum text, not here. An agent must guess whether to call this or search_master_data/resolve_master_data_entity when it only has an approximate identifier.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new behavior: it is a paid x402 call with per-depth price IDs and it returns direction, validity dates, provenance, and confidence — all invisible in the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three dense sentences with the cost model front-loaded and return fields enumerated compactly. The price-ID sentence is long but earns its place by mapping depth values to billing identifiers; nothing else is wasted.

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 only 3 params and no output schema, the description supplies what an agent needs: the entity-domain scope, the return field set, and the pricing tiers. Minor gaps remain around result size/limits at depth 3 and what happens on unknown record IDs, but nothing blocking.

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 67%, and the description compensates by tying `depth` to concrete price IDs (depth-1/2/3), which the schema only states abstractly as "separately priced tier." record_id and entity_type are left to the schema, which is reasonable given their clarity.

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 and resource ("Get governed public relationships for one master-data golden record") and immediately grounds it with concrete examples: supplier ownership, location hierarchy, organization parentage. Combined with the schema note that reference data belongs to get_reference_data, an agent can distinguish this from siblings like get_master_data_golden_record without opening schemas.

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 phrase "for one master-data golden record" implies the usage context and "Paid x402 tool" signals cost-gating, but there is no explicit when-to-use vs. when-not or named alternative within the description itself. The exclusion guidance (customer/asset/person closed; reference data elsewhere) lives in the schema, not the description.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the bar is lower. The description still adds real context: the call is free (cost signal) and the payload covers coverage and freshness metadata, not live records. It omits response size/pagination behavior for the all-entities case.

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: what it returns, then when to call it. Zero filler and the most decision-relevant fact ('use this first') is front-loaded.

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 usefully enumerates the response members (identifiers, attributes, relationships, coverage, freshness), which is the right compensation. Minor gap: it doesn't indicate that omitting entity_type returns the full multi-domain payload or how large that is.

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 itself explains entity_type, the include_* flags, defaults and the empty-object behavior thoroughly. The description mentions no parameters at all, so it adds nothing beyond the structured fields — baseline 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 ('Get') and enumerates exactly what is returned: entity types, identifiers, searchable attributes, relationships, reference domains, coverage and freshness. 'Free discovery tool' frames it as read-only metadata. It does not explicitly name the sibling it replaces (get_reference_data), so it falls short of 5.

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 this first when an agent does not know the data model or valid filters' gives explicit sequencing guidance that clearly separates it from the search/resolve siblings. It implies but never states the inverse (skip it if you already know the model), so no exclusion is spelled out.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuinely new context: it is a paid tool with a specific price ID and it enumerates return fields including provenance and version. It omits pagination/rate-limit behavior, but the paid-upfront disclosure is valuable.

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 sentences, front-loaded with the paid flag and the core purpose. Every sentence contributes (payment, scope/domains, return shape, price ID) with no redundancy.

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

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

With no output schema, the description usefully enumerates the returned fields (codes, labels, definitions, validity dates, mappings, provenance, version), so the agent knows what to expect. Combined with a fully documented schema, only usage-vs-sibling guidance is notably absent.

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 carries the heavy semantic load (e.g., codes as set membership, cursor binding). The description adds nothing about individual parameters beyond the domain concept, so the baseline 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?

The description states a specific verb and resource ('Get governed public reference data and controlled vocabulary values') and enumerates concrete domains (country, currency, unit of measure, etc.). It clearly conveys what the tool returns (codes, labels, definitions, mappings, provenance, version), though it never explicitly contrasts itself with siblings like get_master_data_golden_record or search_master_data.

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?

There is no explicit when-to-use/when-not guidance and no named alternatives among the six sibling tools. The only routing signal is the 'Paid x402 tool' flag, which tells the agent about cost but not about selection vs. the master-data siblings.

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

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this a safe, idempotent, non-destructive read. The description adds genuinely non-derivable context: it is a paid x402 call with a specific price ID, it returns explainable match evidence, and it will not silently choose among ambiguous candidates. It stops short of saying how the payment is settled or what form the returned evidence takes.

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?

Four short clauses, each earning its place: payment model first, then what is matched, then the key behavioral guarantee, then the price ID. No filler and nothing buried.

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 and a nested-object input, the description does enough: it names the entity domains in scope implicitly, discloses the paid nature and price ID, and characterizes the return ('explainable match evidence') and the ambiguity policy. The main gap is the interaction with sibling lookup tools and the input-shape requirement, both of which the agent must find in the schema.

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 67%, including a documented entity_type enum and an anyOf requirement, so the schema carries most of the burden. The description adds nothing about entity_type, identifiers, or the 'at least one of identifiers/attributes' rule, so it neither compensates for the gap nor adds meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and scope: matching incomplete or conflicting supplier/location/organization attributes to trusted master-data candidates, with the no-silent-choice guarantee. It is distinguishable from get_master_data_golden_record and search_master_data by implication, but no sibling is named, so the differentiation is not explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

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

"Incomplete or conflicting" implies the triggering condition, so usage is inferable. However, the description never says when to prefer search_master_data or get_master_data_golden_record instead, nor does it surface the domain exclusions (customer/asset/person, reference data) that the schema carries — an agent would have to open the schema to learn them.

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

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 genuinely new context: the tool is paid via x402, requires reading a pricing resource first, and returns bounded summaries rather than full records. It stops short of explaining what happens on an unpaid call or whether results are cached, which keeps it from a 5.

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?

Four sentences, front-loaded with the payment caveat and the core verb, with the price ID and pricing-resource instruction earning their place. The return-value sentence is a dense field list, but each item is meaningful for an agent judging result trustworthiness.

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?

There is no output schema, so the description carries the return-value burden and does so by naming match reasons, confidence, provenance, public-use status, freshness, and quality scores. Combined with the payment prerequisite and the schema's cursor/limit documentation, an agent has enough to call this correctly; only error and rate-limit behavior are unaddressed.

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 query, limit, cursor, and entity_type are all documented in the schema itself. The description only restates the entity domains ('suppliers, locations, or organizations') and adds no syntax, matching behavior, or pagination detail beyond what the schema provides — baseline 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 and resource ('Search trusted public master data') and scopes the domains to suppliers, locations, or organizations, plus what the result contains. It does not name a sibling to contrast with, so an agent must infer that single-record retrieval belongs to get_master_data_golden_record and reference data to get_reference_data.

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 one concrete prerequisite ('Read masterdata://pricing before payment') and flags that this is a paid x402 tool, which is real usage guidance. It never says when to prefer this search over resolve_master_data_entity or get_master_data_golden_record, so the alternative-selection decision 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.