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

Annotations declare write (readOnlyHint=false), non-idempotent, open-world. The description adds real behavioral context beyond that: hints are auto-retrieved during generation for any project in the domain, and adherence='exact' forces the LLM to follow precisely. It does not address idempotency (what happens if the same hint is added twice), a notable gap for a non-idempotent write.

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 the crucial domain-vs-project distinction, and each sentence carries information. The final adherence/process_type sentence is useful but slightly ancillary to the core purpose, adding mild 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?

No output schema exists, and the description covers purpose, scope, retrieval behavior, and key parameter usage, which is sufficient for a write tool. Remaining gaps (idempotency semantics, permission requirements) are minor but real.

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 the baseline is 3. The description goes beyond the schema by prescribing a concrete parameter pairing (adherence='exact' with process_type='section_discovery') and its effect, which is a usage pattern the schema does not spell out.

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 a guidance hint at domain level) and immediately disambiguates scope: 'applies to ALL projects in the domain, not just one project.' This clearly separates it from the sibling aethis_add_guidance, which operates at project level.

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 for when to use it (cross-section principles like solicitor navigation, discretion model, raw-facts principle) and notes hints are retrieved automatically during generation. It implies the project-level alternative via 'not just one project' but never names aethis_add_guidance explicitly as the alternative to pick instead.

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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds a behavioral note: the guidance applies to domain knowledge absent from source text, and implies adding it affects future generation steps. It does not cover authentication, side effects, or whether existing guidance is replaced. With annotations carrying the safety profile, a 3 is appropriate.

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 action, followed by usage scope and the next step. No waste; every sentence 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?

The tool has no output schema and annotations are moderate. The description gives a basic workflow but omits important details like whether the call is synchronous, whether it replaces existing guidance, and what happens on failure. For a mutation tool with openWorldHint, more context would be expected.

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 description need not explain parameters. It hints at the purpose of guidance_text ('domain knowledge not in the source text') but adds no syntax, format, or default information beyond what the schema already documents.

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: 'Add a guidance hint to a project.' This is clear and actionable. It does not differentiate itself from the sibling aethis_add_domain_guidance, which sounds like it may overlap, but the core operation is unambiguous.

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 use this for 'domain knowledge not in the source text' and directs the agent to call aethis_generate_and_test afterward. This provides clear context and a follow-up action, though it offers no exclusions or when-not-to-use guidance.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuinely useful context beyond that: archived projects are 'preserved but excluded from listing,' which clarifies this is not a hard delete, and flags permanence. It stops short of saying whether the action can be undone.

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 action and followed by the two facts that matter (what happens to the object, and that it is irreversible). 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?

For a single-parameter mutation whose annotations already carry the destructive/idempotent profile, the description covers the essential outcome. It is slightly thin on whether archiving is reversible or requires specific authorization, 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?

Only one parameter (project_id) and the schema already documents it at 100% coverage. The description adds no format, validation, or lookup guidance beyond what the schema states, 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 (Archive) and resource (a project), and immediately clarifies the semantics of 'archive' as preserved-but-hidden. It does not explicitly differentiate itself from the sibling aethis_archive_ruleset, but the resource noun makes the target unambiguous.

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 guidance on when to archive versus using alternatives (e.g. aethis_list_projects, aethis_review_project) or any stated prerequisites such as required permissions or project state. Usage is only implied by the tool name.

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 destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description still adds real value beyond them by stating the post-condition (preserved but excluded from /decide) and the irreversibility ('This is permanent').

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 action and immediately followed by the effect and the permanence warning. 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?

For a one-parameter mutation with no output schema and annotations that already carry the destructive/idempotent flags, the description covers action, consequence, and irreversibility. Only the lack of explicit usage routing keeps it short of full completeness.

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 single ruleset_id parameter is fully documented in the schema, so the description adds no format or semantic detail beyond it. Baseline 3 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?

States a specific verb ('archive') and resource ('ruleset'), letting an agent distinguish it from siblings such as aethis_archive_project and aethis_list_rulesets 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?

The description implies when this is appropriate by explaining that archived rulesets are excluded from /decide resolution, but it never states explicit when-to-use/when-not conditions or names an alternative (e.g., deleting or updating instead).

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the description goes further by disclosing that cancellation 'may be cooperative rather than immediate', that only project ownership is released, that outcomes are 'cancelled or already_cancelled', and that an API key is required. This is meaningful added context, though the destructive/idempotent framing partly restates 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?

Front-loads the core action and the required workflow order, and each sentence carries useful guidance. It runs somewhat long, and the closing 'It is a destructive mutation' sentence largely duplicates the destructiveHint annotation.

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 destructive mutation with no output schema, the description covers the workflow, approval requirement, possible outcomes and API-key need. It stops short of naming when an agent should NOT cancel or listing alternative tools, but the essential invocation 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 description coverage is 100%, so all three parameters are already documented. The description reinforces the binding intent ('bind the exact job_id', confirm_job_id 'protects against accidental target mismatch') but adds little syntax or format detail beyond what the schema already provides.

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 ('cancellation of one observed generation job') and adds scope ('release only its project ownership'), which lets an agent distinguish this from sibling mutations like aethis_archive_project or aethis_publish.

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 names the prerequisite and ordering ('First call aethis_generation_status and bind the exact job_id') and states the required human-approval condition ('agents must obtain a fresh explicit user reply before calling'), leaving little to inference.

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 cover safety (readOnlyHint=false, destructiveHint=false, non-idempotent). The description adds real behavioral context beyond them: the object is created empty (no rulesets, no field vocabulary, no tests) with status='draft', and it requires an API key. It does not describe the returned object's shape, but with annotations carrying the safety profile this is a solid addition.

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 the core purpose, then creation-state semantics and the population workflow. Four compact sentences with little waste; the trailing auth note is useful but slightly bolted-on.

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 creation tool with 100% schema coverage, no output schema, and annotations carrying the safety profile, the description covers the essential extras: post-creation state and the follow-up workflow. The only minor gap is not describing what the create call returns.

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 including the nested robot_hints object are already documented in the schema. The description adds no parameter-level syntax or format detail beyond that, making the baseline 3 correct.

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 ('Create a new Rulebook') and defines it as the composed-whole execution unit that bridges rulesets via outcome_logic. This conceptual framing distinguishes it from aethis_create_ruleset (the parts) without opening either 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 next-step workflow ('Populate afterwards with aethis_create_ruleset for each section, then wire up the field vocabulary and composition logic before publishing') and names a sibling. It lacks an explicit when-not or alternative-selection condition, so it stops short of full routing guidance.

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 disclose the write profile (readOnlyHint=false, idempotentHint=false, openWorldHint=true, destructiveHint=false), so the safety burden is partly carried elsewhere. The description adds the required-test-cases constraint and the follow-up generation step, but says nothing about duplicate-creation risk from non-idempotency, permissions, or what the created artifact looks like.

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 action and immediately followed by the precondition and the next tool. Every clause carries information and nothing is padded.

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 fairly complex tool (7 params, nested test_cases, optional contract_version and expected_review_bindings) with no output schema, the description covers the creation-to-generation flow but omits how the response should be interpreted and when the optional expectation-related parameters matter. It is minimally adequate given the strong schema coverage rather than 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?

Schema description coverage is 100%, so all seven parameters including the nested test_cases shape are already documented in the schema; baseline 3 applies. The description echoes that source_text and test_cases are inputs but adds no format, sizing, or conditional-requirement detail (e.g., contract_version being required when expectations are supplied).

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 ('Create a new rule ruleset with source text and test cases') and flags the TDD framing, so an agent knows this bootstraps a ruleset from source text plus tests. It does not, however, differentiate itself from the sibling aethis_create_rulebook, so the boundary between the two creation tools is left implicit.

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?

Adds real workflow guidance: 'Test cases are required' and 'After creation, call aethis_generate_and_test' tells the agent both a hard precondition and the mandatory next step. It stops short of naming when to prefer this over aethis_create_rulebook or aethis_set_tests, so no exclusions or alternatives are given.

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 read-only/non-destructive/open-world; the description goes further by disclosing the three outcome states (eligible/not_eligible/undetermined), the undetermined payload (next_question, optimal_path), optional trace and explanation, and the API-key requirement per mode. With no output schema, this return-value disclosure is the primary behavioral value and it is covered.

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 the core action and the either/or constraint, then builds outward to mode semantics, return states, and auth. Every sentence carries distinct information; nothing is repeated or padded.

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 six-parameter, nested-object tool with no output schema, the description supplies the missing pieces: mutual exclusivity of the two ID modes, the auth difference between them, and the shape of the non-success outcome. Nothing an agent needs to call it correctly is 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 baseline is 3; the description adds conceptual semantics beyond the schema's field-level text — that a rulebook composes rulesets via outcome_logic and that exactly one of the two IDs must be supplied. It does not add syntax or format detail for field_values beyond deferring to aethis_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+resource (evaluate eligibility) and immediately disambiguates the two modes of operation: single published ruleset vs composed rulebook. The examples (`aethis/uk-fsm` vs `aethis/uk-fsm/child-eligibility`) make the distinction concrete and let an agent separate this from sibling tools like aethis_schema or aethis_next_question.

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?

Explicit routing guidance: 'Provide exactly one,' plus the decision rule — use a rulebook for the whole-form decision, a ruleset for one section in isolation. It also states the auth precondition that selects between modes (rulebook always needs an API key; ruleset can be anonymous against public rulesets).

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=true, destructiveHint=false and idempotentHint=false; the description usefully confirms the iteration model ('call repeatedly ... to improve completeness'), which matches the non-idempotent hint. However, it never discloses that the tool invokes an LLM and may require an Anthropic key or incur cost — that requirement is buried in the schema's key parameters rather than surfaced behaviorally.

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 front-loaded sentences: purpose, return payload, then workflow sequencing. Nothing is wasted, though the return-value sentence could arguably be dropped given how terse the rest is.

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, and the description compensates by naming the returned artifacts (names, types, descriptions, completeness) plus the recommended call sequence. It is largely complete for an extraction tool, with the only real gap being the unstated LLM/key dependency.

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 (including the retired openai_key and the three auth-key variants) are documented in structured data. The description only implies that project_id selects the source-text scope and adds no syntax or format detail beyond the schema — 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 ('Discover input fields from the project's source text') and enumerates the outputs (field names, types, descriptions, completeness). It clearly differentiates itself from the sibling refine_fields, but stays silent on how it differs from validate_fields or set_field_spec, which also touch fields.

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 rule ('Run this BEFORE writing test cases') and names the companion tool to pair with ('Call repeatedly with aethis_refine_fields'). It lacks a negative case (when not to use it vs validate_fields), so it stops short of full routing guidance.

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=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: 'No authentication required' and the exact returned field list. It lacks any statement about pagination behavior or whether results are cached/stable, but it adds real value over 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?

Front-loaded with the core purpose and scope, then usage triggers, return shape, and routing. Every sentence carries information, though the middle clause enumerating return fields and downstream tools makes it dense; a tighter phrasing would read better without losing 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?

There is no output schema, and the description compensates by naming the exact returned fields (slug, ruleset_id, name, description, field_count, rule_count) and the next tools to pass them to. For a two-parameter browse tool with full annotation coverage, nothing an agent needs 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 description coverage is 100%, with both limit and offset fully documented in the schema itself. The description adds no parameter syntax or semantics beyond what the schema provides, 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 and resource ('List public showcase rulesets across all tenants') plus scope, and explicitly distinguishes itself from the tenant-scoped aethis_list_rulesets. An agent can select between the two without opening either 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 explicit triggering conditions ('first-time discovery, demos, or whenever the user asks what rulesets are available without referencing a specific project') and names the sibling it is not (aethis_list_rulesets, tenant-scoped). The when-to-use and the alternative are both 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 readOnlyHint=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, so safety and mutability are covered. The description usefully discloses that the service analyses raw text (implying LLM-driven, non-deterministic output, consistent with idempotentHint=false), but it says nothing about cost, latency, or whether repeated calls vary. Adequate but not rich beyond 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?

Four front-loaded sentences that each carry signal: purpose, input, outcome, ordering, and fallback. Slightly marred by the 'rule rulesets' typo and the ordering/fallback points being split across two trailing sentences, but there is 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?

For a read-only analysis tool with no output schema, the description conveys the purpose, required input, sequencing, and the corrective sibling. It hints at the return ('which sections should be authored as separate rulesets') but never describes the shape of the returned sections, which is the one gap for a tool whose whole value is its output.

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 six parameters are documented in the schema itself. The description only reinforces that raw source text must be supplied (mapping to 'sources'), adding no format or constraint detail beyond the schema. Baseline 3 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?

States a specific verb and resource ('discover the logical sections of source legislation') and goes further by explaining the outcome ('identifies which sections should be authored as separate rule rulesets'). This clearly separates it from siblings like aethis_refine_sections and aethis_validate_sections without opening their 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?

Gives an explicit ordering constraint ('Run BEFORE creating projects') and names the alternative for the failure case ('Call aethis_refine_sections if sections are missing or incorrectly split'). Both the when-to-use and the redirect condition are stated, leaving nothing to inference.

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=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, so the safety profile is covered. The description still adds real value by disclosing what the explanation contains (criteria groups, requirements, exception paths) — important because there is no output schema to describe the return shape.

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?

One sentence, front-loaded with the verb and resource, with the content enumeration appended rather than padded. No redundant restatement of the title or annotations.

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, read-only explain tool this is close to sufficient: the agent knows the input and what the output narrative will cover. It does not note whether the output is scoped/truncated for large rulesets, which is the only notable gap.

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 a single parameter, ruleset_id, and schema description coverage is 100% ('The ID of the published rule ruleset'), so the schema fully documents it. The description adds no format, sourcing, or lookup guidance for the ID, which is the expected baseline-3 outcome when the schema does the work.

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: it returns human-readable descriptions of the rules inside a ruleset, and it names the sub-components covered (criteria groups, requirements, exception paths). The 'human-readable' framing implicitly separates it from the schema-oriented siblings (aethis_schema, aethis_rulebook_schema), but no sibling is named explicitly, 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?

Usage is only implied: an agent can infer this is the tool to call when it needs to understand what a published ruleset actually enforces. There is no explicit when-to-use, when-not-to-use, or pointer to aethis_explain_failure / aethis_schema for related needs.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real value beyond that by disclosing the return payload — diagnosis, criteria with DSL metadata (waivable, review_required), and a fix hint — which is important since no output schema exists.

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 purpose before the usage and return details; every clause carries information. The return-value clause is slightly list-heavy but earns its place given 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?

For a read-only diagnostic tool with full schema coverage, the description supplies the missing piece — what the diagnosis returns — which compensates for the absent output schema. Only the differentiation from aethis_explain is left 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 all four parameters (ruleset_id, field_values, expected_outcome, test_name) are already documented in the schema. The description adds no format or syntax detail beyond it, 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 ('Diagnose why a ruleset produced an unexpected outcome') and scopes it to test inputs, which is clear. It does not explicitly distinguish itself from the sibling aethis_explain, so an agent must infer the boundary between 'explain' and 'explain_failure'.

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 a clear triggering context — 'Use during rule authoring when a test fails' — which tells the agent when this tool is appropriate. It stops short of naming an alternative (e.g. aethis_explain) or stating exclusions, so it is context without 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?

Annotations already declare readOnlyHint=false, idempotentHint=false and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: a 60-120 second runtime, synchronous polling until completion, and the timeout recovery path. It stops short of disclosing cost implications of an LLM-backed run or whether a partial/timed-out generation leaves state behind.

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 with no filler, front-loading what the tool does and then the operational caveats. Every clause (duration, timeout escape hatch, cancel condition) carries information an agent needs at call time.

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 correctly takes on return semantics (pass/fail plus regression detection) and runtime/recovery behavior, which is the right coverage for a long-running compound operation. It could be more complete about prerequisites (a valid Anthropic key is mandatory per the schema) or what happens on a failed run.

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% and the parameter docs are unusually rich (key-source precedence, deprecation and refusal notes). The description adds no parameter-level meaning of its own, so the baseline 3 for a fully documented schema 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 first sentence names a specific compound action (generate rules from source text + run all test cases), and the second clarifies the mechanism (trigger, poll, run). It reads distinctly from siblings like aethis_generation_status and aethis_cancel_generation rather than blurring into them.

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 explicit routing conditions: on polling timeout use aethis_generation_status before retrying, and reserve aethis_cancel_generation for a caller who wants to stop the run. Both the alternative tool and the selecting condition are stated, leaving nothing to inference.

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=true and destructiveHint=false, and the description adds genuinely new context: tenant scoping plus an API key requirement, the server-authoritative nature of worker_lifecycle, and the caveat that a stale heartbeat alone does not imply worker death. That is exactly the kind of operational nuance annotations cannot convey.

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 sentences, front-loaded with the read-only purpose, then the return contract, then the retry caveat and auth requirement. No sentence is redundant, and the field enumeration is justified because no output schema exists.

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 compensates by naming the returned fields (generation_contract_version, telemetry_availability, worker_lifecycle, retry_readiness, progress, safe failure diagnostics), and it covers auth and tenant scoping. Nothing an agent needs to invoke and interpret this call 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?

With a single required parameter and 100% schema description coverage, the schema already documents project_id fully; the description adds only that the lookup is tenant-scoped, not any syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('Check the current generation job for a project') and explicitly marks it as non-mutating ('without changing it'), which cleanly separates it from siblings like aethis_cancel_generation, aethis_generate_and_test, and aethis_refine. The enumerated return fields further pin down what the agent gets back.

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 conditional guidance: 'Retry only when retry_readiness is ready; an old heartbeat alone does not prove worker death,' which tells the agent when a retry is justified. It does not name the sibling retry tool or state when-not-to-call this status tool, so it stops short of full routing guidance.

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 cover the safety profile (readOnlyHint=true, destructiveHint=false), and the description adds material context the annotations lack: public showcase rulesets need no auth while rulebook graphs always require an API key (401 for anonymous callers). It does not, however, explain why idempotentHint is false for a pure read, which is the one behavioral oddity left unaddressed.

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 dense paragraph with the core purpose and the either/or constraint front-loaded, followed by return shape and then auth caveats. It is efficient and well-ordered, though the return-shape sentence is long and could be trimmed.

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 carries the burden of describing the return payload, and it does so concretely ({ruleset_id|rulebook_id, slug, name, graph: {nodes, edges, sections, stats}, mermaid}) plus what display.sentence/routes/expr convey. Combined with usage and auth guidance, an agent has everything needed to call and interpret this 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% and both parameters are fully documented there, including mutual exclusivity and the rb_* / slug formats. The description's "provide exactly one" restates the schema rather than adding syntax or format detail beyond it, 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?

States a specific verb (get) and resource (ruleset-map graph) and explicitly names both input modes: a published ruleset via ruleset_id or a composed rulebook via rulebook_id. It also names the sibling it competes with (aethis_explain), so an agent can distinguish it without opening either 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?

"Use this to visualise or explain a ruleset's/rulebook's structure before or instead of aethis_explain" gives an explicit when-to-use and names the alternative tool. It also states the exclusivity rule ("provide exactly one") and the auth conditions per mode, leaving nothing to inference.

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=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds that only 'active' hints are returned and that they are cross-section, which is useful context, but it omits the notable idempotentHint=false implication and any return-format detail.

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 tight sentences, front-loaded with the action and scope. Every clause earns its place with no filler or 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 does carry the burden of hinting at return content, and it does so briefly ('cross-section hints that apply to all projects'). For a single-parameter read-only list tool this is nearly sufficient, though the shape of an individual hint is left unspecified.

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% for the single 'domain' parameter, which already carries the example 'uk_citizenship'. The description adds no format or constraint detail beyond what the schema provides, 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 ('List all active guidance hints for a domain') and clarifies scope as 'cross-section hints that apply to all projects in the domain.' It implicitly separates itself from the sibling aethis_list_guidance by specifying domain-level scope, but never names that sibling or contrasts them explicitly.

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 when-to-use guidance, no prerequisites, and no alternatives named. The second sentence describes what is returned rather than when an agent should reach for this tool over aethis_list_guidance or aethis_add_domain_guidance.

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=true, destructiveHint=false, openWorldHint=true and idempotentHint=false, covering the safety profile. The description adds the returned fields, which is useful, but says nothing about pagination, ordering, or result size. Adequate but not rich against the annotation coverage.

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: what it does, what it returns, when to use it. Front-loaded with the core action and zero 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, but the description compensates by naming the returned fields (text, source, active status). For a single-parameter read tool with full annotation coverage, this is close to complete, though ordering/scope of 'all' remains unspecified.

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% with a single documented project_id parameter, so the schema does the heavy lifting. The description only reinforces 'for a project' without adding format, ID-source, or scoping 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 ('List all guidance hints accumulated for a project') and adds what each item exposes (text, source, active status). It does not explicitly differentiate itself from the sibling aethis_list_domain_guidance, so it falls 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?

'Use before adding new guidance to avoid duplicates' gives a clear, actionable condition for when to call it, tied to the sibling aethis_add_guidance. No explicit when-not or named alternative is given, keeping it below 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 readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds useful scope context ('current tenant') and enumerates the returned fields, but says nothing about pagination, result limits, or the fact that idempotentHint is false. Adds some value beyond annotations without being rich.

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, purpose first and return contents second, with no filler. Both sentences earn their place, though the second is essentially a return-value preview that could be tightened.

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 previews the return fields (project IDs, names, domains, latest ruleset info). For a zero-parameter, annotation-covered list tool this is close to complete; only pagination/scope caveats are 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?

The tool takes zero parameters, so there is no parameter semantics for the description to carry; the baseline of 4 applies. Nothing in the description misrepresents the empty 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?

The description gives a specific verb and resource ('List all projects') scoped to 'the current tenant', which cleanly distinguishes it from siblings like aethis_list_rulesets and aethis_list_rulebooks. It does not explicitly name or contrast those siblings, but the resource is unambiguous.

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 when-to-use guidance, no prerequisite (e.g. tenant selection), and no routing to alternatives such as aethis_review_project or the ruleset-listing tools. Usage is only implied by the verb 'List'.

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 cover readOnly, destructive, idempotent, and openWorld. The description adds what annotations do not: tenant scoping and the API-key requirement. It does not discuss pagination or volume limits, but with annotations carrying the safety profile this is solidly above baseline.

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 returns, then usage, then auth and hand-off. The long field enumeration is justified because no output schema exists, though it is denser than strictly necessary.

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 supplies the return fields, the scope/auth constraint, the triggering intent, and the follow-up tools that consume rulebook_id/slug. An agent has everything needed to call it and use the result.

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 tool takes no parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The enumerated return fields add value but belong to output semantics, not parameters.

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 ('List rulebooks') and immediately defines the resource ('composed wholes that bridge multiple rulesets'), which distinguishes it from the sibling aethis_list_rulesets without opening either 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 an explicit trigger ('when the user asks "what rulebooks exist?"') and a second disambiguation scenario (checking whether several `<ns>/<x>/*` rulesets are bridged into one parent). It also routes forward to aethis_decide and aethis_rulebook_schema.

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=true and destructiveHint=false, so safety is covered. Because there is no output schema, the description carries the return-value burden and does so concretely by naming every returned field, including the non-obvious 'version history' and the active/archived status values. It leaves the unusual idempotentHint=false unaddressed, and mentions no pagination behavior.

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 states the action and scope, followed by a compact enumeration of returned fields. The inline UK citizenship example is mildly verbose but genuinely clarifying for the 'name' field, so it largely 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?

With no output schema, the description does the necessary work of enumerating return fields, which makes it adequate for a one-parameter read tool. The gaps are the lack of differentiation from aethis_discover_rulesets and any statement about result size or pagination.

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 a single parameter with 100% schema description coverage, so the schema already documents project_id fully. The description adds only the loose phrase 'for a project' and contributes no format or sourcing detail beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 rulesets) and enumerates exactly what each entry contains — ID, name, status, version, field count, rule count. It does not, however, distinguish itself from the sibling aethis_discover_rulesets, which an agent could easily confuse with this tool.

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 says the tool operates 'for a project' but gives no when-to-use guidance, no prerequisites, and no routing away from alternatives such as aethis_discover_rulesets or aethis_list_rulebooks. The agent must infer the choice from the name alone.

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=true, destructiveHint=false, and idempotentHint=false; the description adds genuine behavioral context beyond them — a stateful iterative loop keyed on accumulating answers, and the surfacing of author notes under a Notes block. No contradiction with the non-idempotent hint (each call reflects new state). It stops short of describing auth, error behavior, or the response shape.

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 what the tool returns and then the calling protocol; the Notes-block detail is placed last as secondary information. 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?

With no output schema, the description carries more burden but handles the key termination signal ('until decision is reached') and the Notes block. It still doesn't describe the response structure (question text, options, how a final decision is represented), which an agent driving the loop would benefit from knowing.

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 the baseline is 3, but the description goes further by defining the semantics of field_values over time (empty dict for the first call, then collected answers) — information the schema's field description only partially conveys. ruleset_id is left to the schema, which is acceptable given full coverage.

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 gives a specific verb+resource ('Get the optimal next question') and frames it within a conversational eligibility check, which separates it from decision/explanation siblings. However, it never names an alternative tool or explicitly contrasts itself with siblings like aethis_decide or aethis_explain, so sibling differentiation remains implicit.

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 clearly states the usage pattern: call with empty field_values for the first question, then accumulate answers and call again until a decision is reached. This is strong procedural context, but it offers no explicit when-not-to-use or named alternatives, 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?

Annotations declare non-read-only, non-idempotent, non-destructive, but the description adds materially more: tests run first, failure blocks publication, force bypasses, and the previous active ruleset is auto-deprecated. The auto-deprecation side effect is exactly the kind of context annotations do not convey.

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, zero waste, with the core action and its gating condition front-loaded. Every sentence carries distinct information (action, test gate, side effect).

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 mutation tool with no output schema, the description covers the key risk behaviors an agent needs: test gating, force override, and deprecation of the prior ruleset. What publish returns and whether the deprecation is reversible is left unstated, a minor gap.

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 the schema already documents all four parameters, including the force semantics the description echoes. The description reinforces force but adds nothing about name or label beyond what the schema states, 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 (Publish) and resource (the latest ruleset) with clear scope, and separates itself from create_ruleset/aethis_update_rulebook by operating on the 'latest' existing ruleset. It stops short of naming a sibling, so sibling differentiation is only implied.

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 conditional (tests must pass unless force=true), which implies when the tool will refuse, but it never says when an agent should choose publish over create_ruleset or the rulebook update tools. Usage is inferable rather than stated.

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=false, openWorldHint=true, idempotentHint=false, destructiveHint=false. The description adds real behavioral context beyond that: the edit is deliberately minimal, passing tests must stay green, the full suite is re-run, and feedback is applied before regeneration. It does not say whether the call blocks or returns a job handle, which matters given the generation-status/cancel siblings.

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 verb+resource and the edit constraint, then the routing rule. No filler; every clause conveys an operational fact (minimality, test-preservation, suite re-run, alternative tool).

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 mutating, open-world tool with no output schema and no idempotency guarantee, the description covers what changes but not what comes back or whether the operation is synchronous. Given sibling tools like aethis_generation_status and aethis_cancel_generation, the absence of any note about job/async behavior or result reporting leaves a real gap.

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% and all six parameters (including the auth-key variants) are documented in the schema itself, so the baseline is 3. The description only adds that feedback is optional and is applied 'before regenerating'; it says nothing about the key-resolution parameters, which is acceptable since the schema handles them.

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 ('Refine an existing published ruleset') plus the exact mechanism: add optional feedback, make the MINIMAL edit to fix failing tests, re-run the full suite. The parenthetical 'seed-from-existing incremental re-authoring' further pins the operation. It is clearly distinguishable from the from-scratch sibling it names.

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?

Explicit routing guidance: 'Use this to fix a specific finding without re-authoring the whole section; use aethis_generate_and_test for a from-scratch rebuild.' That names an alternative and the condition selecting it. It does not, however, disambiguate from the very close siblings aethis_refine_sections and aethis_refine_fields, which an agent must also choose between.

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=false, openWorldHint=true, idempotentHint=false and destructiveHint=false, covering the mutation/safety profile. The description adds that the operation appends a 'field_extraction' guidance hint and re-runs discovery, which is useful behavioral context, but it discloses no auth requirements or reversibility detail beyond that.

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 with the trigger condition front-loaded. The first and third sentences overlap somewhat ('Add guidance to improve field discovery' vs 'Adds a field_extraction guidance hint and re-runs discovery'), a minor 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?

For a non-read-only, non-idempotent mutation tool with no output schema, the description conveys purpose, trigger, and the resulting side effect adequately. Remaining gaps around auth handling are covered by the well-documented key parameters 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 100%, so the schema already documents all six parameters including the feedback example. The description adds no syntax or format detail for parameters beyond what the schema provides, 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 and resource: adding field-discovery guidance and re-running discovery. It reads clearly and implies a distinct role from siblings like aethis_discover_fields or aethis_add_guidance, though it does not explicitly contrast itself with those tools.

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 trigger condition: 'Use when fields are missing, misnamed, or enum values are incomplete.' However, it names no alternative tool or when-not condition, so routing against siblings like aethis_validate_fields 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.

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

Annotations already declare a non-read-only, non-idempotent, open-world operation, but the description adds the crucial detail that feedback is persisted as a domain-level guidance hint and that discovery re-runs immediately. This explains the non-idempotent persistence and the iteration model, which the annotations alone do not convey.

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 action and then the when-to-use condition. Slight redundancy between 'immediately re-runs discovery so you can see the effect' and 'Repeat until the section list matches your expectations,' but nothing 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?

For a 7-parameter mutation tool with no output schema, the description explains the iteration loop and what the re-run produces. The sensitive API-key parameters are handled thoroughly in the schema itself, so the description need not repeat them, though it could note that key configuration is required to run.

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 documents domain, feedback, sources, and the key parameters in detail. The description restates that feedback is a 'guidance hint' and that sources are the same documents, but adds no syntax or format detail beyond the schema, 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 sequence (add guidance, then re-discover sections) on a specific resource (sections), and the 'refine' scope is distinguishable from the sibling aethis_discover_sections. An agent can tell it apart from a plain discovery call 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 explicit trigger conditions: 'when sections are missing, incorrectly split, or named differently than expected,' plus a termination condition ('repeat until the section list matches your expectations'). It doesn't name aethis_discover_sections as the alternative explicitly, but the context is clear enough.

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 cover read-only, non-destructive, open-world, and non-idempotent. The description adds real behavioral context beyond them: it is advisory-only, the deterministic path needs no LLM key, and coach=true requires a configured Anthropic key. It does not explain why the read is non-idempotent (the LLM narrative can vary), a minor omission.

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 sentences, front-loaded with purpose and return shape before the advisory/key caveats; no filler. Slightly dense but every sentence carries information an agent needs.

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 carries the return-value burden and does so: it enumerates score, per-check evidence dimensions, strengths, and the next improvement. Combined with the advisory-only note and key requirements, an agent has everything needed to call it 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?

Schema description coverage is 100% and the schema itself documents every parameter in detail, including the key-resolution chain and the retired openai_key. The description only restates the coach/key relationship, adding framing but no semantics beyond the schema, 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 (review) and resource (authoring project) plus the rubric it applies, and describes the distinctive output (score, per-check evidence across grounding/process/lifecycle, strengths, next improvement). This separates it cleanly from the sibling validate/refine/explain tools, which do not produce skill-building feedback.

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?

Tells the agent this is advisory and 'never blocks publishing', which contrasts usefully with the gating validate_* siblings, and explains the condition for opting into coach=true. It stops short of an explicit 'use this instead of X when Y' routing statement, so it is clear context rather than full when/when-not guidance.

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=true and destructiveHint=false, so the safety profile is covered by structured data. The description adds return-structure detail but discloses nothing behavioral beyond the annotations (no auth requirements, rate limits, or error behavior), so a baseline 3 is appropriate.

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 well-ordered sentences: purpose first, return contents second, usage and parameter format third. Appropriately sized and front-loaded, with only minor redundancy in the third sentence where the slug/id format restates the 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?

There is no output schema, so the description carries the full burden of explaining return values and does so thoroughly (AST expression, ruleset fields, union of required inputs). Combined with complete parameter documentation, an agent has everything needed to call and interpret the 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 the single rulebook_id parameter is already fully documented with the same slug/opaque-id examples the description repeats. The description adds no format or semantics beyond what the schema provides, so the baseline 3 holds.

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 the composition + aggregated input fields for a rulebook) and enumerates exactly what is returned (outcome_logic AST, bridged rulesets list, union of required fields), which helps separate it from siblings like aethis_list_rulebooks or aethis_schema. Sibling differentiation is present but indirect rather than 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?

Gives a clear condition and names an alternative: 'Use this BEFORE aethis_decide on a rulebook_id to know what field_values to supply,' plus a secondary use 'to inspect how a rulebook is wired.' No explicit when-not guidance, but the intended call context is unambiguous.

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=true and destructiveHint=false, so safety is covered; the description adds useful context by enumerating the shape of the returned data (names, types, descriptions, allowed values). It stops short of describing error behavior or what happens for unpublished rulesets.

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 purpose, then the return shape, then the workflow instruction. No filler or 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 correctly compensates by summarizing the returned fields, which is the key information an agent needs to chain into aethis_decide. Only minor omissions remain (e.g., behavior for missing or unpublished ruleset_id).

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 single ruleset_id parameter is documented in the schema itself ('The ID of the published rule ruleset'). The description adds no syntax, sourcing, or format guidance beyond that, 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?

Specific verb+resource: it fetches the input fields required for an eligibility check, and explicitly states what it returns (field names, types, descriptions, allowed values). It is clearly tied to aethis_decide, though it does not differentiate itself from the similarly named sibling aethis_rulebook_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?

Provides explicit sequencing guidance: 'Use this before calling aethis_decide,' which tells the agent exactly when in the workflow to invoke it. It does not, however, state any exclusions or conditions under which this tool should be skipped.

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 description goes well beyond the annotations by disclosing automatic downstream validation ('every aethis_discover_fields call automatically validates discovered fields against this spec'), the resulting mismatch hints in the validation_result block, persistence across sessions, and precise note-handling behavior ('Omit notes to leave existing note guidance unchanged; pass an empty list to clear it'). These are concrete behavioral consequences not captured by readOnlyHint, idempotentHint, or destructiveHint.

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 purpose and then adds usage and behavioral detail in a logical order. It is somewhat verbose: the automatic validation and mismatch-hint sentences overlap, and the note-handling sentence duplicates schema text, but no sentence is entirely wasted for a setter with nested configuration.

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 a two-parameter setter with nested expected_fields and no output schema, the description covers purpose, usage timing, downstream effects, persistence, and note semantics. One notable gap remains: it does not specify whether expected_fields replaces the entire existing spec or merges with it, leaving replacement semantics ambiguous.

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 documents both parameters and their nested fields in detail. The description's note-handling sentence largely restates the schema's own notes description ('Omit to leave existing notes unchanged; pass [] to clear them') without adding new semantic detail, so it meets the baseline for high-coverage schemas.

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: 'Store the expected field specification for a project.' It clearly identifies the action and object, but does not directly differentiate the tool from sibling setters like aethis_validate_fields or aethis_refine_fields within the purpose statement itself; that differentiation comes later as an ordering instruction.

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 says when to call: 'Call this BEFORE running aethis_discover_fields when the SME has already defined the field vocabulary.' That gives a clear context for use, but it does not state when not to use it or name alternative tools for other scenarios, so it falls short of full when/when-not/alternatives guidance.

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 destructiveHint=true and idempotentHint=false, but the description adds what that means operationally: prior tests are replaced wholesale, cardinality limits (1-100 legacy, up to 500 with contract_version: 1), a capability gate on the target API, and a recovery instruction after interruption. This is meaningful context beyond the structured hints.

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 the action and scope, followed by limits, the destructive warning, the capability gate, and the recovery note in descending order of importance. Dense but each sentence carries a distinct constraint; slight clause-stacking in the second sentence keeps 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 a destructive, open-world mutation with nested objects and no output schema, the description covers prerequisites, scope of destruction, limits, and post-interruption recovery. It does not describe permission or auth requirements beyond the capability advertisement, and gives no hint about the response shape, which is a modest remaining gap.

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 baseline is 3, but the description adds semantics the schema does not: the 1-100 vs up-to-500 split tied to contract_version. That nuance clarifies how the two caps interact, which is not derivable from maxItems: 500 alone.

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 (replace) and resource (the complete reviewed test suite) scoped to an existing project, and explicitly bounds what it does NOT do: 'without creating a project or changing its sources, fields, or guidance.' That negation cleanly separates it from siblings like aethis_refine_fields or aethis_generate_and_test.

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 real preconditions: 'after field discovery' and 'The target API must advertise replacement support before any write.' It also handles the failure path ('If the response is interrupted, inspect the project before approving another replacement'). It stops short of naming an alternative tool when replacement support is absent, so no explicit routing for that case.

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=false, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds two genuine facts beyond that: it requires an API key (auth requirement) and it behaves as a PATCH, leaving omitted fields untouched. It does not say what happens on a missing rulebook_id or whether the updated rulebook is returned.

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 mutable fields and followed by the two operational constraints. No filler; each sentence carries information, though the structure is plain prose rather than optimized.

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 5-param partial-update tool with full schema coverage and a safety annotation set, the description covers what can change, that at least one field is required, that omissions are preserved, and the auth requirement. No output schema exists, so return values need not be described; only error behavior on an invalid rulebook_id is left 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 in the schema, including the detailed robot_hints beat list. The description only restates the same field names, adding the parenthetical 'assistant guidance for the conversational agent' which the schema already states. Baseline 3 is correct.

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 (update) and resource (Rulebook) and enumerates the exact mutable fields: name, description, slug, robot_hints. An agent can tell this is the mutation counterpart to aethis_create_rulebook, though no sibling is named explicitly.

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?

'Provide at least one field to change; omitted fields are left as-is' communicates partial-update semantics, which is useful invocation guidance. However, it never says when to reach for this tool versus aethis_create_rulebook or the various refine/validate tools, and gives no exclusions or preconditions.

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/openWorld/non-destructive, and the description adds meaningfully beyond them: tenant-scoped, requires an API key, the rolling 24h window, and the relative scarcity of `generate` vs metered-but-unlimited `read`. These are behavioral facts the agent could not infer from 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?

Dense but front-loaded: the purpose leads, followed by field detail, then the operational trigger and constraint. No sentence is filler, despite the length.

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 supplies the return shape (per-class used/limit/remaining/reset), the auth requirement, and the scoping. Nothing an agent needs to call it correctly 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?

Zero parameters, so the baseline of 4 applies. The description instead documents the response fields (used, limit, remaining, reset time) which is useful but not a parameter concern.

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 (show the caller's rate-limit budget per operation class) and enumerates the exact operation classes and fields returned. It is unmistakably distinct from siblings like aethis_generation_status or aethis_list_projects.

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 prescribes when to call it ('before a large authoring run') and the downstream behavior (report remaining `generate` budget to the user) so a 429 is never the first signal. That is a clear triggering condition plus rationale.

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 cover the safety profile (readOnly, non-destructive, openWorld), but with no output schema the description carries the return-value burden and does so thoroughly: it enumerates the diff categories (missing, type mismatch, enum mismatch, extra) and defines the all_match condition including the edge case that extra fields do not affect it. This is substantive behavior disclosure beyond 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?

Six tightly packed sentences, front-loaded with what the tool asserts and the all_match contract, followed by sequencing guidance. Each sentence carries distinct information (return shape, success condition, edge case, precondition, failure path) with no 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?

For a two-parameter read-only assertion tool with no output schema, the description supplies everything an agent needs: the precondition (after discovery), the success criterion, the meaning of extra fields, and the remediation call on failure. Nothing material 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 expected_fields, key, sort, and enum_values are all documented in the schema itself. The description references an 'expected field specification' but adds no syntax or value-format guidance beyond that, so the baseline 3 for fully-covered schemas 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 ('Assert that the discovered fields match an expected field specification') and clearly positions the tool as a verification step distinct from discovery and refinement siblings. The phrase 'discovered fields' and the field-spec language differentiate it from aethis_validate_sections without opening either 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?

Explicit when-to-use ('Run after aethis_discover_fields to verify field coverage before writing test cases') and explicit next step when it fails ('call aethis_refine_fields with guidance about the missing or incorrect fields'). Both the trigger and the alternative are named, leaving nothing to inference.

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=true and destructiveHint=false, so the safety profile is covered. The description goes beyond that by disclosing the shape of the result (missing vs extra) and the follow-up action, though it says nothing about the odd idempotentHint=false or any cost/size behavior.

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: purpose/return shape first, then when to call, then the conditional next step. Every sentence earns its place with 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?

With no output schema, the description takes on the burden of explaining the return value and does so (missing and extra sections). Combined with annotations covering safety and the workflow branch covering next steps, an agent has everything needed to call it 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?

Schema description coverage is 100%, so the schema already documents domain, expected_sections, and discovered_sections with formats and examples. The description only implies the expected-vs-discovered distinction and adds no syntax or format detail beyond the schema, 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 (compare/validate) and resource (discovered sections vs expected specification), and names exactly what the result contains (missing and extra sections). This cleanly distinguishes it from aethis_validate_fields and from aethis_discover_sections, which it explicitly references.

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 explicit sequencing ('Call after aethis_discover_sections') and an explicit remediation branch ('If sections are missing, call aethis_add_domain_guidance with adherence="exact"'), including the argument value to pass. No inference is required.

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