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

Annotations only declare readOnlyHint=false and destructiveHint=false, so the description carries the real behavioral burden and does so well: deterministic/non-LLM verdicts, explanations sourced from ingested policy docs, free-tier domain limits, and the `missing_parameters` contract that determines whether a verdict is provisional. It also documents `rule_firings` causal ordering and `asserted_facts`, which the agent could not infer otherwise.

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?

It is long, but front-loaded with the verdict mechanism and its guarantees before the Args block, and each paragraph adds distinct information (audit trail, free-tier behavior, missing_parameters semantics). Some prose in the Args block is verbose enough that it could be tightened, keeping it from a 5.

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 an 8-parameter tool with an output schema (so return values need not be described) and only safety annotations, the description supplies everything an agent needs: input semantics, mode selection, free-tier constraints, the next_step handoff, and how to interpret missing_parameters. Nothing material is left unstated.

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 0% across 8 parameters, so the description must compensate, and it does: every parameter is explained with examples (facts, fact_sources with audit implications, unstructured_text extraction, the three response_mode values, and the two pattern flags). The fact_sources explanation adds meaning the schema cannot convey (typed vs evidence-read facts recorded as 'request').

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 opening sentence names a specific verb and resource ('Make a deterministic, auditable decision in a domain') and immediately characterizes the mechanism (Rete rule engine, never the LLM). This clearly separates it from siblings like list_rules, put_rules, get_parameters, and ingest_text, which manage rules/documents rather than produce a verdict.

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 gives real operating context: no API key means demo domains only, and it points to get_parameters to discover which fields a domain's rules test. It also tells the agent what to do with `next_step`. It stops short of explicit when-not-to-use routing (e.g., 'use put_rules to define a domain before calling decide'), so a 4 rather than 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 only declare readOnlyHint=true; the description adds real context beyond that: results are derived from the account's own rule copy (so custom domains are included) and parameters are ordered most-decisive-first by max_salience, which explains why ordering is meaningful. No auth, freshness, or pagination disclosure, 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?

Purpose is front-loaded in the first clause, followed by useful output-shape and ordering detail; the sentence structure is scannable. The enumeration of return fields is slightly listy but each item carries semantic weight (units/scales warning, salience ordering).

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, the description need not explain return values, yet it usefully clarifies ordering and scope. For a one-parameter read tool with annotations covering safety, the only material omission is the `domain` argument's expected format.

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 0% for the single `domain` parameter, so the description must carry the semantics. It conveys that domain scopes to a rule set and that custom domains work, but never states the expected identifier form (key, name, or ID), leaving a real gap.

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 the input parameters a domain's rules decide on') and immediately positions it relative to the sibling `decide`. An agent can distinguish it from `list_rules`, `get_rule_source`, and `decide` 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?

Explicitly frames the tool as the prerequisite step — 'the facts to collect before calling `decide`' — which routes the agent through a concrete workflow. It names no when-not condition or alternate path (e.g. when to use `list_rules` instead), so it falls 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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely useful behavior beyond it: that the return includes parsed rules and an editability flag, and the demo-domain copy semantics. It stops short of describing freshness, size, or error behavior for unknown domains.

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 primary outcome before the usage cue. The final demo-domain sentence is a little convoluted ('your own copy's rules once you have edited it, otherwise the shared demo's') but still earns its place by explaining a non-obvious behavior.

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?

An output schema exists, so return shape need not be spelled out, and the description rightly focuses on behavior and sequencing. Given a single trivial parameter, the only real omission is any hint about valid domain values, which keeps this just short of complete.

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, 'domain', with 0% schema description coverage, so the schema adds nothing and the description must compensate. The description only obliquely implies what a domain is (via the demo-domain sentence) and never clarifies naming format or where to discover valid domains.

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 ('Fetch') and resource ('a domain's rule set as editable YAML') and enumerates what comes back (parsed rules, edit permission). It partially differentiates from siblings by emphasizing editable source YAML, but never explicitly contrasts with list_rules, so an agent must still infer which of the two rule-retrieval tools it wants.

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 an explicit sequencing cue: 'Use this before `put_rules` to see the current rules', which clearly names the downstream tool this complements. It lacks any when-not guidance or a named alternative (e.g. list_rules) for read-only inspection.

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?

The annotation readOnlyHint=true already discloses the read-only nature. The description adds context by specifying it is scoped to 'this account' and includes 'remaining monthly quota,' which is useful. It does not disclose other behavioral traits like caching or data freshness, but for a simple usage check this is acceptable.

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 a single sentence, front-loaded with the action 'Show,' and contains no redundant words. Every word contributes to understanding the tool's purpose and scope.

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 tool is simple with no parameters and has an output schema that likely describes return values. The description covers the purpose and scope, making it complete for an agent to understand and invoke correctly.

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 are zero parameters, so the baseline is 4. The empty schema already covers all parameter information, and the description adds no unnecessary detail. This is appropriate.

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 'Show' and clearly identifies the resource: the account's decision usage, plan, and remaining monthly quota. This distinguishes it from sibling tools like 'decide' or 'list_rules' that serve different purposes.

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 implies usage by stating it shows account usage and quota, suggesting it would be used to check limits before making decisions. However, it does not explicitly state when to use it or mention alternatives such as the 'decide' tool that consumes quota.

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?

Beyond the readOnlyHint annotation, it discloses that nothing is saved, describes the return payload (validated draft rules, rule→rule edges, overlap warnings, citation fields), and warns to review drafts before persisting. This adds significant behavioral context not captured by the annotation.

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 densely informative but well-structured: purpose first, then return details, then critical workflow warning, then parameter docs. Every sentence earns its place with no fluff or repetition.

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?

Given the output schema exists, the description successfully covers all essential contextual aspects: what the output contains, citation tracking, no side effects, and the recommended persistence workflow. It is a complete mental model for an agent to act correctly.

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?

Despite 0% schema coverage, the description defines both parameters: domain ('an owned domain or a new name') and policy_text ('max ~50k characters'). This adds meaningful semantic constraints and context beyond the bare schema property names.

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 opens with a specific verb and resource: 'Convert a written policy document into DRAFT decision rules.' It clearly distinguishes itself from sibling tools like put_rules (persist) and list_rules (list existing rules) by emphasizing the draft and no-save aspects.

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 explicitly states when to use this tool and what to do next: 'NOTHING IS SAVED: review the drafts... then persist explicitly with put_rules — validate first with dry_run=true.' This provides a concrete workflow and names the exact sibling tool for 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?

Annotations only tell the agent this is a non-destructive write; the description adds substantial behavior beyond that: chunking/embedding, citation of ingested text in future decisions, plan-limit consumption, demo-domain copy semantics, and the team-plan admin-only restriction. That is exactly the kind of side-effect and authorization detail a caller needs.

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-loads the core action, then layers the consequential behavioral details, then lists args cleanly. It is somewhat dense but every sentence carries decision-relevant information; nothing is padding.

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?

An output schema exists, so return values need not be described. Combined with the permission/plan/copy semantics and full parameter coverage, an agent has everything needed to invoke this correctly in a domain-mutating scenario.

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 0%, so the description carries the burden and does so for all three params: domain ('existing or new'), text ('policy or reference text'), and source ('shown in the document list'). The text param is nearly a restatement of its title, keeping this from a 5.

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 ('Add policy/reference text to a domain's knowledge base') and clarifies the downstream effect (chunked, embedded, cited in future decisions). An agent can distinguish this from siblings like put_rules or import_policy_rules, which operate on rules rather than raw document text.

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 decision context: the domain may be existing or new, creating a new domain claims it for the account, and ingesting into a demo domain makes a private copy. It does not, however, explicitly name alternatives (e.g. import_policy_rules) or state when not to use this tool, so it falls short of full when/when-not routing.

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?

The readOnlyHint annotation already declares safe read-only behavior, and the description adds the scope of 'ingested into a domain's knowledge base.' It does not discuss pagination, ordering, or return details, but for a simple list tool with annotation coverage, this is acceptable.

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?

A single, front-loaded sentence with no filler. Every word earns its place.

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?

Given the simple one-parameter input, the presence of an output schema, and a clear scope in the description, it is mostly complete. It could benefit from noting whether results are sorted or paginated, but those are non-critical gaps for a basic listing 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 0%, so the description must compensate. It only mentions 'domain's' in passing, which implies the domain parameter selects the knowledge base, but it does not explain domain's format, requiredness, or behavior. The single parameter is simple, but the description adds minimal value.

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 ('List') and resource ('documents ingested into a domain's knowledge base'), clearly stating what the tool does. It differentiates from siblings like list_rules by targeting documents rather than rules.

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 clear context: this lists documents from a domain's knowledge base, which implies when it should be used versus other tools like ingest_text or put_rules. However, it does not explicitly state exclusions or alternatives.

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?

Goes well beyond the readOnlyHint annotation by detailing the return structure: condition formats (flat AND list or when tree), verdict, salience, asserted facts, edges with forward-chaining semantics, citation purpose, and overlap warnings. This gives an agent a thorough understanding of what to expect from the tool.

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?

Five sentences pack a high density of information without fluff. Front-loaded with the primary action, each subsequent sentence adds meaningful semantics (return fields, edges, citation, overlap warnings) and ends with a practical use case. No word 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?

The description fully contextualizes the tool: what it lists, what the output contains, why edges and citations matter, and how the domain parameter behaves. Given the simple schema (1 optional param) and presence of an output schema, this description is complete enough for an agent to use the tool correctly.

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 input schema has no parameter description (0% coverage), but the phrase 'one domain (or all domains)' clarifies that the `domain` parameter filters to a specific domain while null/omission means all domains. This is valuable, though it doesn't explicitly name the parameter or mention validation/format.

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 opens with 'List the decision rules for one domain (or all domains),' clearly stating a specific verb and resource with a scope qualifier. It also distinguishes the tool from siblings like `decide` by positioning it as a read-only listing tool for learning domain expectations, and its focus on rules differentiates it from `list_documents` and `get_rule_source`.

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 a clear when-to-use signal: 'Use this to learn which fact fields a domain expects before calling `decide`.' This explicitly ties the tool to a pre-decision workflow, but it lacks an explicit 'when not to use' or named alternatives for related operations like retrieving the original policy text (get_rule_source).

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 flag a destructive write, and the description goes well beyond them: domain claiming and plan limits, demo-copy semantics, pre-save validation, dry_run behavior, rejected produce/consume cycles, response contents (ok/errors, parsed rules, overlap warnings), and a warning that dropping `citation` silently loses the policy link.

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?

Purpose is front-loaded and every paragraph adds real information for a YAML-authoring tool, but three full YAML examples make it long; the citation example is valuable while the second tree-form example is somewhat verbose for what it teaches.

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, destructive, 0%-coverage schema with an output schema present, the description covers everything an agent needs: YAML grammar, validation/dry-run path, cycle rejection, domain claiming, and the import_policy_rules citation handoff.

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 0%, so the description must carry the load and does: `domain` is 'an owned domain, or a new name to claim', `dry_run` is 'validate only, without saving', and `rules_yaml` is documented in depth with flat/tree forms, conditions-vs-when exclusivity, and `not` semantics.

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?

Opens with a specific verb and resource: 'Create or replace a domain's rule set from YAML.' It clearly distinguishes itself from siblings like list_rules, get_rule_source, and import_policy_rules by describing authoring/persistence rather than reading or draft import.

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 context: first save to a new domain claims it (plan limits apply), saving to a demo domain creates a private copy, and dry_run validates without persisting. It also names the import_policy_rules handoff, though it never states explicitly when another tool should be preferred over this one.

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