NOMOS

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

Annotations are sparse (readOnlyHint=false, openWorldHint=false, idempotentHint=false), and the description adds genuinely useful context the annotations cannot: no auth for public authorities, a permanent cryptographically-bound transcript (query_id + url) is produced, and the verdict comes from sealed rules rather than paraphrase. The non-read-only hint is consistent with the described permanent transcript write, so no contradiction. It does not discuss rate limits, latency, or error behavior for unknown authorities.

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 sibling differentiation, then response behavior — a sensible order with no wasted lead-in. Some phrasing is promotional rather than operative ('Nothing is invented or paraphrased', 'replayable evidence, not just a reply') and could be trimmed without losing decision-relevant 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?

For a nested-input, external-marketplace query tool with five parameters, the description covers auth tiers, what gets returned, and how to escalate detail. An output schema exists, so the description's return-value detail is a bonus rather than a requirement. Only error handling for malformed or unknown authority slugs is 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 every parameter is already documented, including the include_evaluation_trace default/trace tradeoff and the authority slug format. The description reinforces the default-vs-trace behavior but adds little syntax or format meaning beyond the schema. Baseline 3 applies when the schema carries the parameter burden.

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 ('Query a published authority on the NOMOS Exchange marketplace') and immediately scopes it against a named sibling ('a different system from verify_decision's own governance artifacts'). An agent can distinguish this from verify_decision, generate_governance, and detect_contradictions without opening any 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 routing context: this hits external published authorities, public ones need no key, licensed ones need an nxk_ key beyond a free allotment. It also tells the caller to omit include_evaluation_trace unless the diagnostic record is actually needed. It lacks an explicit 'use this when...' trigger phrase or stated exclusions for the other siblings, so it stops just 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.

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

Annotations already declare readOnly/idempotent/closed-world, and the description adds genuinely new context: nothing is persisted and no artifact is created, which matters for a policy-analysis call. It stops short of mentioning API key requirements or input size limits, so it is strong but not complete.

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, front-loaded with the core action and followed by the stateless guarantee and the result taxonomy. The category list is dense but each entry conveys distinct output an agent needs for interpretation.

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 an output schema present and full parameter coverage, the description covers purpose, statelessness, and result types adequately for a three-parameter analysis tool. It could note auth or document volume expectations, but nothing critical for correct invocation is missing.

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

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

Schema coverage is 100%, so both the document fields and behavioral_logs are already documented in the schema, including the layer_divergence note the description repeats. The description adds no format, sizing, or api_key nuance beyond structured data, so 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 ('Analyze policy documents ... to detect contradictions') and enumerates the exact output categories (threshold_conflicts, ghost_terms, role_conflicts, rule_collisions, layer_divergences). The 'Stateless — no artifact is created' clause separates it from the artifact-producing siblings like generate_governance.

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?

Implies usage through 'optional behavioral decision logs' enabling layer_divergence detection, which tells the agent when to supply extra input. However, it never states when to choose this over the adjacent siblings (verify_decision, ask_authority) or what preconditions the documents must meet.

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 not read-only, not open-world, and not idempotent. The description adds meaningful behavior beyond them: LLM-based extraction, contradiction detection, ARI computation, cryptographic sealing, returned artifact_id, and the confidence-tier effect of behavioral logs. It does not cover cost, latency, or overwrite semantics, so it is 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?

Four front-loaded sentences with no filler: first states the transformation, then the processing steps, then the return value, then the optional input effect. Every sentence carries operational 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?

For a complex mutation tool with an output schema and full parameter descriptions, the description covers the key workflow and output linkage. Minor omissions—such as cost, latency, or explicit overwrite/idempotency behavior—are not fatal because annotations and schema cover much of the contract.

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 explains name, organization, documents, domain, api_key, and behavioral_logs. The description adds conceptual value for behavioral_logs (behavioral evidence layer / CERTIFIED tier) but little for the other parameters; 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 ('Convert ... policy documents into a sealed NOMOS governance artifact') and enumerates the processing steps: rule extraction, contradiction detection, ARI scoring, and sealing. It also names the downstream sibling verify_decision, but does not explicitly differentiate itself from detect_contradictions despite the overlap.

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?

Provides implied usage context—use it to produce an artifact_id for verify_decision, and optionally supply behavioral logs to reach CERTIFIED tier—but gives no explicit when-to-use versus detect_contradictions or ask_authority, nor when not to use it.

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 readOnlyHint, idempotentHint, and closed-world, so the safety profile is covered. The description adds genuine non-annotation context: the response shape is not uniform, `allowed` is the only field safe to read across both variants, and the two shapes correspond to two different backend endpoints. It stops short of stating failure modes (invalid artifact_id, contract mismatch on inputs) or rate limits.

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

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

The core guarantee ("Always returns `allowed`") is front-loaded and the shape divergence is explained before the artifact list. It is information-dense but the enumeration of pub_* IDs and their domains duplicates the schema's artifact_id description, which is the one removable block.

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 tool with a polymorphic response, nested objects, and mixed authentication requirements, the description covers auth (no key for pub_*), the polymorphic return contract, a cross-reference to outputSchema for exact shapes, and the available demo artifacts. An agent has everything needed to call it correctly without guessing the response 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 including the pub_* ID list and the api_key/domain_id split is already documented in structured data. The description largely restates the schema's artifact_id guidance rather than adding new meaning about how `decision` must match an artifact action or how `inputs` keys are validated. Baseline 3 applies when the schema carries the load.

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?

"Check whether an AI decision is allowed, denied, or needs escalation according to a sealed NOMOS governance artifact" names a specific verb (check/verify), a specific resource (a decision against a sealed artifact), and the three possible outcomes. It is clearly distinguishable from siblings generate_governance (producing artifacts) and detect_contradictions (auditing rules), and the mention of artifact types further narrows the scope.

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 concrete routing guidance between artifact classes: use pub_* IDs for public demos with no API key, and your own Studio artifact IDs (plus domain_id) for custom governance. It does not explicitly state when to prefer this tool over ask_authority, so the sibling-level exclusion is missing, but the intra-tool selection guidance is strong.

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