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

With no annotations, the description carries real weight: it discloses the return payload (decision, matched_rules, reasoning, errors, identity, content hash, Receipt) and precisely what the receipt_hash binds (table_id, table_version, table_hash, context_hash). It does not cover auth/permission requirements or error semantics for invalid tables, so it falls short of 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?

Front-loaded with purpose then routing logic, and each sentence carries distinct information; it is dense but slightly overstuffed, with return-value enumeration and chaining responsibilities packed into a single paragraph.

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?

Despite no output schema and no annotations, the description enumerates the response fields, the receipt's hash coverage, and the caller's chaining obligation, so an agent knows both how to call it and what to expect back.

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 already 100%, so the baseline is 3, but the description adds genuine semantic meaning: the version-defaulting rule, the ad-hoc-vs-governed tradeoff, and why context_hash and previous_hash exist (cryptographic binding and chaining).

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 ('Evaluate a DMN decision table against instance context') and immediately distinguishes the governed (table_id) path from the ad-hoc (table_json) path, separating it from siblings like register_decision_table and list_decision_tables.

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

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

Explicitly says to give table_id or table_json (not both), explains the default version behavior, and prescribes the external context-only path via omitted instance_path with a named example (MTCP Evidence Packs). It also states when to pass previous_hash and who owns chain persistence.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the result will be PERMIT, DENY, or INDETERMINATE with a receipt, but it does not state whether the operation is read-only, what permissions are required, what the receipt contains, or how INDETERMINATE should be handled.

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

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

The description is two compact sentences with the core action and return values front-loaded. There is no filler, and every phrase contributes useful information.

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

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

The schema fully documents the four parameters, and the description covers the return values. However, without annotations or an output schema, the definition leaves important context unstated: read-only behavior, receipt meaning, failure modes, and when this tool is preferable to related governance tools.

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

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

Schema description coverage is 100%, so all four parameters are documented in the schema itself. The description adds no further parameter semantics such as actor identity requirements, path formats, or how target_state is resolved, so it remains at the baseline.

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

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

The description names a specific verb and resource: evaluating whether a workflow transition is permitted. It also states the return categories, making the operation concrete. It does not explicitly distinguish itself from siblings like get_allowed_transitions or evaluate_decision, so it stops short of a 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?

The description states what the tool does but gives no guidance on when to use it versus get_allowed_transitions, validate_governance, or evaluate_decision. There are no exclusions, prerequisites, or alternative-routing instructions.

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?

No annotations are provided, so the description carries the full disclosure burden. It partially compensates by describing the return shape (list of transitions with target state info and paths), but says nothing about whether the operation is read-only, permission requirements, or behavior when the current state has no valid transitions.

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 short sentences with the core purpose front-loaded and no wasted wording; the return-value sentence follows immediately and earns its place since there is no output schema.

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 annotations and no output schema, the description does supply the essential return-shape information and implies the read context. It falls short only on operational traits (errors when no transitions exist, read-only nature), which are not covered elsewhere.

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

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

Schema description coverage is 100%, so both schema_path and instance_path are already documented in the schema. The description adds no further meaning about the parameters, 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?

States a specific verb+resource: 'Get valid next states from the current workflow state', with the return content ('valid transitions with target state info and path(s)'). It doesn't name or contrast with the sibling evaluate_transition, so an agent can't fully distinguish the two from the description alone.

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?

Usage is only implied – the phrasing suggests you call it when querying what states are reachable. There is no explicit when/when-not guidance and no mention of alternatives such as evaluate_transition (which likely tests a specific target rather than enumerating options).

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?

With no annotations, the description carries the full burden, and it does disclose the return fields (model_id, model_label, has_governance, active dimensions), which is real behavioral value. However, it never states that the operation is a read-only inspection, nor what happens with an invalid or non-governed XSD path.

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 short sentences, front-loaded with the purpose and followed by the return shape. Nothing is wasted and no sentence repeats the title or name.

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

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

For a single-parameter inspection tool with no output schema and no annotations, the description covers purpose plus the returned fields, which compensates for the missing output schema. It falls short only on error behavior and explicit read-only framing.

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?

There is one required parameter with 100% schema description coverage ('Path to the SDC data model XSD file'), so the schema already does the work. The description only implicitly connects the parameter to 'the model' and adds no format or path-resolution detail 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 resource: 'Report which governance dimensions the model defines,' which tells an agent exactly what information comes back. It does not distinguish itself from sibling governance tools like validate_governance or get_allowed_transitions, so the agent must infer the boundary.

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 no when-to-use guidance, no prerequisites, and no mention of alternatives among the many governance-related siblings. An agent has to guess whether this is the right entry point versus validate_governance.

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?

With no annotations, the description carries the behavioral burden and does well: it discloses the ordered result set (lowest version first) and the important conditional behavior that supplying table_id expands each row to include full table JSON. It omits payload-size/pagination implications of that expansion and any permission or scope constraints, so not 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?

Two dense sentences: return shape and ordering first, filtering second, and the receipt-resolution rationale last. No filler and no restatement of the tool name.

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

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

For a read-only listing tool with no output schema, the description supplies the returned field set, ordering, and conditional payload expansion, which is most of what an agent needs. It stops short of covering the unfiltered case and the potentially large full-JSON response when table_id is given.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds meaning beyond the schema: it frames table_id as the receipt-resolution path and confirms that domain narrows the version list. It does not clarify behavior when both parameters are supplied together or that filters are optional.

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 (list registered decision tables) and enumerates exactly what is returned per version: table_id, version, table_hash, domain, policy, registered_at. It is clearly separable from siblings such as register_decision_table (write side) and evaluate_decision (evaluation), so an agent can pick it 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.

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

Gives concrete usage context: use it to filter by table_id or domain, and specifically to resolve a receipt's table_id/table_version back to the rules that applied. It does not state when not to use it or what to do if neither filter is supplied (full registry dump), which keeps it below 5.

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?

No annotations are supplied, so the description carries the full disclosure burden. It reveals only that a record is written and returned; it says nothing about persistence, append-only/immutability semantics, whether the action is idempotent, or what permissions or ordering the hashes require. For a mutation tool with zero annotation coverage this is a substantial gap.

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 short, front-loaded sentences with no filler; the purpose leads and the return behavior follows. It is efficient, though it is arguably too terse for an eight-parameter mutation tool rather than needlessly verbose.

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 eight parameters, no annotations, and no output schema, the description should explain storage location, immutability guarantees, and what 'PROV record content' actually contains. None of that is present, leaving the agent under-informed for a write operation of this shape.

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

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

Schema description coverage is 100%, so every parameter is already documented in the schema and the baseline is 3. The description adds no extra semantics for the eight parameters — notably nothing on how entity_hash_before/after relate to the recorded action or how agent_ref differs from agent_name.

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 ('Record a provenance event') and anchors it to a well-known standard ('W3C PROV-O record'), which tells an agent exactly what kind of artifact is produced. It does not name any sibling tool as a contrast, so it stops short of full differentiation.

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 statement of when to record provenance versus when to use the governance/decision siblings, no prerequisites, and no exclusions. The agent must infer the trigger condition entirely from the tool name and the surrounding toolset.

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?

With no annotations, the description carries the full burden and does so well: it discloses idempotency semantics, conflict refusal behavior, optional persistence to a server tables directory, and that table_hash is a SHA-256 of RFC 8785 canonical JSON. It omits authorization requirements and the exact error surface beyond the version-conflict case, 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?

Dense but front-loaded: the primary action and its consumer (evaluate_decision) come first, followed by return fields and then the conflict rules. Every sentence carries information, though the parenthetical hash explanation is somewhat heavy for the space it occupies.

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

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

No output schema exists, but the description enumerates the returned fields (table_id, version, table_hash, domain, policy) and covers persistence and idempotency. An agent has everything needed to call this correctly for a 5-parameter write tool.

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

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

Schema description coverage is 100%, so all five parameters are already documented in the schema; baseline is 3. The description adds meaning about how version immutability and table_id stability govern future lookup and about table_hash derivation from table_json, but adds no format or constraint detail 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 (register) and resource (decision table) plus the key scoping concepts — stable table_id, immutable version — and ties its purpose to a named sibling, evaluate_decision. An agent can distinguish it from list_decision_tables or evaluate_decision 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.

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

Gives clear when-to-use context: register so evaluate_decision can reference the table and receipts record the policy version. It also resolves the main ambiguity an agent would face — re-registering identical content is a no-op, conflicting content is refused and must become a new version. It stops short of naming sibling tools for checking what is already registered (e.g. list_decision_tables).

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?

With no annotations, the description must carry the behavioral burden. It discloses the return fields and the model-only mode, but it does not state whether validation is read-only, what permissions are needed, or how errors are reported beyond returning an 'errors' field.

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 compact sentences, with the core action front-loaded and the return fields listed immediately afterward. There is no redundant or filler text.

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 two-parameter validation tool with no output schema, the description provides enough to understand the core behavior and returned fields. It could be stronger by clarifying read-only behavior or error semantics, but the essential context is present.

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

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

Schema coverage is 100%, so both parameters are already fully documented in the input schema. The description adds no syntax or format detail beyond what the schema provides, which fits the baseline of 3.

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

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

The description uses a specific verb and resource: 'Full governance validation of an instance against its model.' This clearly distinguishes it from status-only siblings such as get_governance_status, though it does not explicitly name an alternative.

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

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

It explains the behavior when instance_path is omitted, but that same information is already in the schema. It gives no guidance on when to choose this tool over get_governance_status or evaluate_decision.

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?

No annotations are provided, so the description carries the full behavioral burden. It helpfully discloses the recomputation behavior, return fields, and RFC 8785 canonicalization rules, but it does not explicitly state that the operation is read-only, whether it has side effects, or what happens on malformed input.

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

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

The description is front-loaded with the core purpose, followed by return values and canonicalization details. Every sentence contributes useful information without redundant or filler content.

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

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

The description covers the input expectations implicitly through the schema, explains the return fields since no output schema exists, and documents the canonicalization algorithm. It is nearly complete for a verification tool, though it could mention whether the operation is purely read-only and how errors are surfaced.

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

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

The single parameter has 100% schema description coverage, and the schema already explains that the JSON string must include evidence_pack_hash and that the hash is recomputed over remaining fields. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline of 3 applies.

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

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

The description uses a specific verb (verify) and resource (MTCP Evidence Pack), and explains the exact mechanism: recomputing evidence_pack_hash. It distinguishes the tool from siblings such as evaluate_decision and validate_governance by focusing narrowly on integrity verification.

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 makes clear that this tool is for integrity verification via hash recomputation, giving an agent enough context to select it. However, it does not explicitly state when not to use it or name an alternative for broader governance validation.

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