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

With no annotations, the description carries the full burden of behavioral disclosure. It only says 'Create', implying mutation, but does not explain side effects, required permissions, validation behavior, or the distinction between chat agents and workflow agents. This is a significant gap for a create operation.

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 single-sentence description is concise and front-loaded, but the brevity is not appropriate for a tool with 8 parameters and no other structured documentation. It is a minimum-viable statement but lacks the substance expected given the tool's complexity.

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 8 parameters, 0% schema coverage, no annotations, and no output schema, this description is severely incomplete. It does not explain required inputs, behavioral effects, return values, or how chat and workflow definitions differ. An agent would have no way to construct a valid call without opening 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 0% and the description gives zero parameter guidance. It vaguely hints at a chat vs workflow distinction (possibly 'agent_type') but does not explain any of the 8 parameters, including required fields like name, description, or goal_prompt. The agent must open the schema to understand what to provide.

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 clearly states the action ('Create') and the resource ('a chat or workflow agent definition'). It distinguishes itself from list/get/update siblings through the 'definition' framing, though it does not explicitly clarify how this differs from ambient_agent_create. The verb-resource pair is specific enough for basic selection.

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

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

No guidance is provided on when to use this tool versus alternatives like yaaif_agent_update or yaaif_ambient_agent_create. The description does not mention prerequisites, suitability conditions, or any exclusions, leaving the agent to infer usage solely from 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?

With no annotations provided, the description must carry the full behavioral burden. It only states the action and one feature (includes skill_ids), but does not disclose anything about error behavior, authentication, read-only nature, or response format. For a get operation, this is thin and leaves the agent to guess what exactly is returned or what happens on failure.

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

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

The description is a single, front-loaded sentence that directly states the purpose. There is no filler or redundancy, making it optimally concise for its 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?

Given the absence of an output schema and the large number of sibling tools, the description is too sparse. It does not clarify the exact structure of the returned agent definition, nor does it delineate this from similar tools like yaaif_agent_spec_get or yaaif_ambient_agent_get. An agent would need more context to use 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?

The sole parameter agent_id is left completely unexplained. Schema description coverage is 0%, so the description must compensate, but it merely says 'by id' without clarifying what the ID is, how to obtain it, or its expected format. This provides no added meaning beyond the parameter name.

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

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

The description clearly states the action (get), the resource (agent definition), and the identifier (by id). It also adds a distinguishing detail (includes skill_ids) that separates it from list-like siblings such as yaaif_agent_list. This is specific and 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?

The description implies usage (to fetch a single agent by ID), but it does not explicitly mention alternatives or when not to use it. Since it is clear from the context that this is the retrieval tool versus creation or update tools, it meets the 'clear context, no exclusions' bar, but lacks explicit routing compared to tools that name sibling alternatives.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a read-only list operation and gives scope, but it does not mention pagination, defaults, result size, ordering, or any operational constraints. This is thin for a tool with three optional filtering parameters.

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

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

The description is a single front-loaded sentence with no filler and includes a useful scope qualifier. It is concise, though the terseness contributes to the lack of parameter and usage guidance.

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

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

For a tool with three undocumented optional parameters and no output schema or annotations, the description is incomplete. An agent cannot determine what q does, how limit behaves, what agent_type values are accepted, or what the response looks like.

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

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

Schema description coverage is 0% and the description provides no meaning for q, limit, or agent_type. The parenthetical '(chat and workflow)' might relate to agent_type, but it does not explain the parameter. The description adds essentially nothing beyond the raw parameter names.

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

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

The description states a specific verb ('List') and resource ('agent definitions') with a clear tenant scope and the included types ('chat and workflow'). It is clear enough to distinguish from get/create/update agent tools, though it does not explicitly name or contrast sibling list tools such as yaaif_agent_spec_list.

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

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

No guidance is given about when to prefer this tool over alternatives like yaaif_agent_get, yaaif_ambient_agent_list, or yaaif_agent_spec_list. The description only states what the tool does, not when to use it or when not to use it.

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

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

With no annotations the description must carry behavioral disclosure, but it only mentions permission and audit logging. It fails to state what the operation does or its side effects (e.g., changing activation state, idempotency, failure modes). The described constraints are useful but insufficient.

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 text is short and readable, with no fluff, but it is under-specified rather than concise. The first sentence is a fragment, and the second lists requirements without grounding them in the tool's purpose.

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-parameter tool with no annotations, no output schema, and a terse description, the agent lacks enough context to call it correctly. The description omits the core action, parameter semantics, expected return, and any error scenarios.

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

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

Schema coverage is 0% and the description names none of the five parameters. It adds no meaning to spec_id, expected_version, override_reason, idempotency_key, or override_approver. The agent still has to guess what each field is for.

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?

Description is a fragment ('Exceptional activation only') that never states the verb or resource; it neither says 'Override activation' nor identifies what is being activated. It is close to a tautology of the name and does not distinguish from siblings like yaaif_agent_spec_adopt or yaaif_agent_spec_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?

No guidance on when to use this tool vs alternatives. It implies exceptional use and permission needs but never names an alternative or a condition that should redirect to another tool.

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?

There are no annotations, so the description must carry the behavioral burden. It does disclose two important effects: existing authored Scenario prose is preserved and a baseline revision is published. However, it does not explain version-mismatch behavior, irreversibility, or side effects beyond publishing, leaving some uncertainty for a mutation tool.

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

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

Two short sentences carry the core action, prerequisite, and key behavioral guarantee with no filler. The description is well-structured and front-loaded.

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

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

For a mutation tool with no annotations and no output schema, the description omits the meaning and source of expected_version, the relationship to yaaif_agent_spec_adoption_preview results, and what the agent should expect in return. This leaves a meaningful gap for a tool with only two required parameters.

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

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

Schema description coverage is 0%, and the description does not explain either parameter. spec_id is inferable from the name, but expected_version's role as a concurrency/version guard is not described, so the agent lacks the semantic detail needed to pass it correctly.

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

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

The description uses a specific verb ('Apply') and resource ('previously reviewed adoption preview'), and clarifies the outcome ('baseline revision is published'). This distinguishes yaaif_agent_spec_adopt from the sibling yaaif_agent_spec_adoption_preview, which generates rather than applies the preview.

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?

'Previously reviewed' is an explicit precondition, so the agent knows the tool should only be invoked after a preview has been reviewed. It does not explicitly name alternatives or say when not to use the tool, but the workflow 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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It says 'Preview', implying read-only, but it doesn't explicitly state that no changes are made, nor does it describe what the preview returns or any side effects. The behavior is only implied, not disclosed. For a preview tool, stating that it is non-mutating and describing the output format would be essential.

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

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

The description is a single, compact sentence that is front-loaded with the action 'Preview'. Every word contributes to the purpose without redundancy. It is concise and well-structured.

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

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

Given the lack of annotations, output schema, and the minimal description, this is incomplete. Key terms like 'bindings', 'live baseline', and 'authored fields' are undefined, and the return value of the preview is not described. An agent would struggle to know what to expect or how to interpret the result. The description is too brief for a tool with this level of complexity and sibling ambiguity.

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 schema has one parameter, spec_id, with no description (0% schema coverage). The tool description does not explain what spec_id refers to beyond the name, leaving the agent to guess that it identifies an agent spec. Since the schema does not help and the description lacks detail, this is a significant gap.

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

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

The description clearly states the verb 'Preview' and the resources: 'selected existing bindings', 'current live baseline', and 'authored fields preserved by adoption'. It indicates a preview operation related to adoption, distinguishing it from generic previews like yaaif_agent_spec_sync_preview by mentioning adoption specifically. However, it doesn't explicitly differentiate from other preview tools in the sibling list, so it's clear but not maximally distinct.

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 guidance on when to use this tool versus alternatives. The sibling list includes many related tools like yaaif_agent_spec_adopt, yaaif_agent_spec_sync_preview, and other previews, but the description gives no indication of the appropriate context or prerequisites. An agent would have to infer usage from the name and the adoption-related phrase.

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

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

With no annotations provided, the description must carry the full behavioral burden. It reveals the default source but fails to disclose whether this is a write operation, what happens on conflict, prerequisites (e.g., existence of entity/slot), or any side effects. Major behavioral ambiguities remain.

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 concise and front-loaded, with no filler words. However, it is so brief that it omits critical information. It earns a middle score for being non-verbose, but the content is inadequate for the tool's complexity.

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

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

Given the tool's complexity (8 parameters, 4 required, no annotations, no output schema), the description is grossly incomplete. It does not explain required parameters, expected_version semantics, slot_key meaning, entity_id usage, or any operational details. The agent cannot safely invoke this tool based on the provided description.

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

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

Schema description coverage is 0%, and the description does not explain any of the 8 parameters (spec_id, expected_version, slot_key, entity_id, kind, source, plan_slug, entity_name). It merely mentions 'default source' without elaborating the source parameter or any other. The description must compensate for the lack of schema documentation and fails entirely.

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 ('Bind') and the objects involved ('live catalog entity' to 'Scenario architecture slot'), which is clear and not a tautology. It also mentions a default source, adding some specificity. However, it does not explicitly distinguish it from sibling tools like yaaif_agent_spec_upsert_slots, so it misses a differentiation point.

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

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

The description gives no guidance on when to use this tool versus alternatives such as yaaif_agent_spec_upsert_slots or sync tools. The only contextual note is the default source, but it does not explain conditions, prerequisites, or exclusions.

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

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

With no annotations, the description carries the behavioral disclosure burden. It explains the effect of each resolution mode, which is useful, but it does not mention side effects, reversibility, permission requirements, or how expected_version guards against stale updates.

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

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

The description is a single compact sentence with no filler, and the core purpose is front-loaded. It is appropriately concise, though the brevity contributes to missing semantic detail.

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 five parameters, no output schema, and no annotations, the description is incomplete. An agent cannot determine how to source conflict_id, what expected_version represents, whether merged_value is mandatory for merge, or what a successful resolution 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 0%, so the description must compensate. It partially explains the resolution enum and hints that merge uses merged_value, but it leaves spec_id, conflict_id, expected_version, and the conditions under which merged_value is required undocumented.

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 clearly states the action ('Resolve one conflict') and enumerates the three resolution modes with their distinct effects. It is specific enough to distinguish this tool from siblings like yaaif_agent_spec_conflicts, though it could more explicitly tie it to agent spec conflicts.

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

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

The description implies usage when a conflict exists and offers resolution options, but it does not state when to prefer this tool over alternatives, how to obtain conflict_id, or any prerequisites like listing conflicts first. No exclusions or alternative tool references are provided.

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

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

With no annotations, the description carries the full behavioral burden. 'List' implies a read-only operation, and the described output fields add context. But it does not explicitly state whether the call has side effects, how results are ordered, or what happens when there are no conflicts.

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

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

The description is a single front-loaded sentence with no filler. Every word adds meaning: the action, the resource, the scope, and the expected output fields.

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 simple one-parameter list tool, this is reasonably complete: it describes what is listed and what the results contain. It lacks an explicit explanation of spec_id and any note about empty results, but the core calling context is covered.

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 only parameter, spec_id, has zero schema description coverage and the description never mentions it or explains what it refers to. An agent must infer from the tool name alone, so the description provides no semantic value for the required argument.

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

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

The description names a specific verb ('List'), a precise resource ('unresolved field-level Scenario/catalog conflicts'), and the distinguishing output ('severity and the two competing values'). This clearly separates it from siblings like yaaif_agent_spec_conflict_resolve and other agent-spec 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?

The intended use is clear: call this when you need to see unresolved field-level conflicts for a spec. However, it does not explicitly state when not to use it or point to the conflict_resolve sibling for actually resolving those conflicts, so it stops short of full alternative 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?

With no annotations, the description must fully disclose behavior. It implies a read-only operation via 'Check', but does not confirm side effects, return format, permissions, or any other behavioral aspects. This is a significant gap for a tool with zero 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?

The description is a single sentence, concise and front-loaded with the action and subject. It contains no filler or redundant wording. While it is brief, it is efficiently structured.

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 there is no output schema, no annotations, and only an undocumented parameter, the description is incomplete. It does not clarify what 'coverage' means, what the tool returns, or how the agent should interpret the results. An agent would struggle to use this correctly without additional context.

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

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

The single parameter spec_id has no description in the schema (0% coverage), and the tool description does not explain what it refers to. The parameter name hints it is an ID, but without further context, an agent cannot be certain what value to pass. The description fails to compensate for the schema's lack of detail.

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 ('Check') and a specific resource ('Scenario slot coverage against the live tenant catalog'), which distinguishes it from other agent_spec tools like agent_spec_get or agent_spec_list. It is not a tautology, but the meaning of 'coverage' is domain-specific and not fully explained.

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 provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or sibling tools to consider. There is no explicit context for when this check is appropriate.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose that the tool creates a resource and returns a spec_id to be used later, which is a meaningful behavioral cue. Yet it omits other relevant behavior such as idempotency, failure modes, or permission requirements, leaving the agent to infer the rest from the create verb. Some transparency is present, but it is not comprehensive.

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

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

The description is two sentences with no filler. The primary action is front-loaded, the Admin UI terminology note adds quick comprehension, and the spec_id follow-up is useful. Every sentence earns its place and the structure is efficient.

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

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

For a tool with a complex nested schema, no output schema, and no annotations, the description is far too sparse. It does not explain what a Scenario/Agent Spec is, the meaning of segments/slots/requirements, the role of required fields like slug and name, or how the returned spec_id should be used in subsequent tools beyond a vague pointer. The description leaves critical operational and compositional details 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 0% and the description does not compensate for it. The phrase 'requirement segments + architecture slots' only vaguely references the segments, requirements, and slots parameters, without clarifying the structure, required fields, relationships, or expected formats. The seven parameters, including nested objects like slots and segments, remain largely unexplained, so an agent would struggle to construct a correct payload.

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

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

The description opens with the specific verb 'Create' and the resource 'tenant Scenario (Agent Spec)', making the primary action unmistakable. It adds useful context by clarifying that the Admin UI calls this a scenario and by naming the main payload components (requirement segments, architecture slots). Among a large set of yaaif_agent_spec_* siblings (list, get, update, publish, etc.), this is clearly the creation 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 implies usage when a new scenario needs to be created and provides a workflow hint ('Pass the returned spec_id on later create tools'). However, it gives no explicit guidance on when to prefer this over similar tools like yaaif_agent_spec_update or yaaif_agent_spec_upsert_slots, nor does it mention exclusions such as existing specs. Adéquate but not explicit.

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

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

No annotations are provided, so the description carries the full burden. It discloses that the operation is only allowed under specific conditions (no catalog bindings, not active, not a release dependency), which is meaningful behavioral context beyond a bare 'delete'. It does not mention irreversibility or permissions, but the constraints are valuable.

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

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

The description is a single efficient sentence that states the action and the key constraints without any fluff. The main verb and resource are front-loaded, and every word adds value.

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

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

The description captures the core purpose and preconditions but is incomplete for an agent to call the tool correctly. The expected_version parameter is unexplained (likely a concurrency guard), and behavior on failure or consequences of deletion are not covered. With no output schema or annotations, the description leaves important operational details unresolved.

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

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

Schema description coverage is 0% and the description does not explain either parameter. 'spec_id' and 'expected_version' are entirely undocumented in prose, so an agent has no additional meaning beyond the raw schema names. The description fails to compensate for the lack of schema 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 clearly states a specific action ('Delete') and a specific resource ('Scenario (Agent Spec)') with a distinguishing qualifier ('empty'). It is easy for an agent to tell this apart from sibling tools like yaaif_agent_spec_update or yaaif_agent_spec_delete_requirement, even 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?

The description provides preconditions ('Allowed only when...') that act as usage restrictions, but it does not explicitly contrast this tool with alternatives or state when an agent should choose a different tool. The usage context is implied rather than directly 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?

With no annotations, the description must carry behavioral disclosure. It communicates destructive intent and a necessary prior step, but does not explain failure behavior if the requirement is still referenced, whether deletion is permanent, or how the expected_version parameter gates the operation.

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 say exactly what the tool does and what must happen first. No filler, and the core action is front-loaded.

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

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

For a multi-parameter deletion tool with no annotations, no parameter descriptions, and no output schema, this description is too sparse. It omits parameter semantics and key behavioral details such as concurrency checking and effect on slot references, leaving an agent to guess.

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

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

Schema description coverage is 0%, so the description should define the three parameters. It only hints at 'requirement' and 'slots' without mapping them to req_key, spec_id, or expected_version, and expected_version remains entirely unexplained.

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

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

The description names a specific operation ('delete one unreferenced requirement') and identifies the resource type (requirement), which distinguishes it from sibling tools that delete slots (yaaif_agent_spec_delete_slot) or whole specs (yaaif_agent_spec_delete). The 'one' qualifier also clarifies scope.

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

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

It gives a clear precondition: remove the requirement from its slots first, and confines the tool to 'unreferenced' requirements. It does not explicitly name alternative tools, but the slot-removal instruction effectively routes the agent to slot-deletion operations first.

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

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

No annotations are provided, so the description carries the full burden. It discloses the destructive nature via 'Delete' and the unbound precondition, but doesn't mention irreversibility, concurrency via expected_version, behavior if the slot is bound, or side effects.

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 sentence with no filler, front-loading the action and scope. Every word earns its place, though the terseness contributes to missing context elsewhere.

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 3-parameter operation with no annotations and no output schema, the description leaves critical context unexplained: what an architecture slot is, what 'unbound' means, why expected_version is required, and what happens if the slot is bound or deletion fails.

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

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

Schema description coverage is 0% and the description names no parameters. It doesn't explain spec_id, slot_key, or expected_version, nor how they identify the slot or protect against concurrent modification.

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 ('Delete'), a specific resource ('one unbound architecture slot'), and singular scope ('one'), which distinguishes it from bulk operations like upsert_slots and from deleting an entire spec via yaaif_agent_spec_delete.

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

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

No guidance on when to choose this over siblings. It doesn't mention yaaif_agent_spec_upsert_slot for adding/updating slots or yaaif_agent_spec_delete for whole-spec deletion, and it doesn't state prerequisites beyond the word 'unbound'.

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

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

With no annotations, the description must carry the behavioral burden; 'Return' signals a read operation and the sentence identifies the graph's components. However, it does not mention prerequisites, failure modes, output shape, or whether the graph is computed on demand, leaving meaningful gaps.

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 sentence front-loads the action, resource, and purpose, then lists the graph contents. There is no filler and no repetition of schema information.

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

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

For one required parameter, the description is close to adequate, but because there is no output schema and no annotations it should say more about the returned graph structure and prerequisites. The listed components (requirements, slots, bound objects, evidence) offer a sketch, not a complete contract.

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

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

Schema coverage is 0% and the description never mentions spec_id, its format, or how it selects the scenario. The parameter name is inferable from the tool name, but the description adds no semantic value beyond what the schema already shows.

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 ('Return') and resource ('Scenario dependency graph'), and gives the analytic purpose ('change-impact analysis'). It also lists the graph's contents, which helps separate it from the broader family of spec tools, though it does not explicitly contrast it with yaaif_agent_spec_release_dependencies.

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

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

The phrase 'for change-impact analysis' provides clear context for when the tool is appropriate. It does not name alternatives or explicitly state when not to use it, 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?

With no annotations, the description carries the burden. It explicitly states 'non-destructive' and 'records readiness conflicts only', which clarifies that it doesn't modify anything and only captures a specific type of data. This is valuable behavioral disclosure, though it doesn't mention return format or any rate limits.

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

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

Two sentences with no filler. The key characteristics (non-destructive, records only) are front-loaded, and the pointer to sync preview/apply is a natural next step. Efficient and well-organized.

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

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

The tool is simple (one optional param, no output schema), but the description omits what the scan returns and fails to explain the 'limit' parameter. It provides enough to invoke the tool but not enough to interpret results or use the parameter correctly. Given the simplicity, a more complete description was 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?

The description does not mention the 'limit' parameter at all, and the schema provides no description either (0% coverage). The agent is left to guess what 'limit' does—likely a maximum number of results, but not stated. Since there is only one parameter, the description should at least hint at its meaning.

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 clearly states the verb ('Run'), the resource ('Scenario drift scan'), and the scope ('non-destructive', 'records readiness conflicts only'). It distinguishes itself from the sync tools (preview/apply) which are for resolving conflicts, so an agent can tell this is a read-only diagnostic.

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 points to 'sync preview/apply' as the resolution tools, which helps routing after a scan. However, it doesn't compare with other scan-like tools (e.g., yaaif_agent_spec_readiness, yaaif_agent_spec_coverage) to clarify when this specific scan is preferred over them. The guidance is useful but not exhaustive.

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

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

No annotations are provided, so the description carries the full burden. It only states the action of recording and the source types; it does not disclose idempotency, overwrite/append behavior, validation of spec version, permissions, or side effects. The presence of an idempotency_key in the schema hints at possible idempotency, but the description does not mention it.

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

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

The description is a single concise sentence that front-loads the verb and object. It contains no extraneous words and is easy to parse.

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

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

For a tool with 11 parameters, no schema descriptions, no annotations, and no output schema, this one-sentence description is insufficient. It does not explain the meaning of required fields like expected_version or requirement_key, nor what the operation returns or how it handles existing evidence. An agent would need to guess several parameter semantics.

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

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

Schema description coverage is 0%, so the description must compensate for 11 parameters. It adds context for the 'kind' parameter by listing the three enum values, but it does not explain 'result', 'spec_id', 'expected_version', 'requirement_key', 'payload', 'source_id', 'expires_at', 'provenance_uri', 'idempotency_key', or 'summary'. This leaves the agent to infer their meaning from names and types.

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 identifies a specific verb ('Record') and resource ('requirement-level verification evidence') and enumerates three evidence sources. However, it does not explicitly differentiate this tool from its sibling 'release_provenance_record' or other evidence-related tools, though the context is reasonably specific.

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

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

The description states when to use the tool: to record evidence from a passed agent test, ambient smoke run, or audited manual attestation. It provides clear context but no explicit exclusions or alternatives; it does not mention when not to use it or point to a sibling tool.

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

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

With no annotations provided, the description carries the full disclosure burden. It states what the tool returns (including segments, slots, bindings, and workflow_design) but does not mention the read-only nature, any side effects, permission requirements, or pagination. Since it is a 'Load' operation, the read-only implication is reasonable but not explicit. The description adds some behavioral context but lacks safety and side-effect disclosure.

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

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

The description is a single sentence that front-loads the verb and resource and then enumerates included contents. It is efficient and has no fluff. Not quite a 5 because it could be even more compact, but it is well-structured.

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 simple get-by-id/slug operation with a single parameter, the description is fairly complete: it names the resource, selection criteria, and key content included. It lacks explicit return format details or error conditions, but given the simplicity and no output schema, the provided information is sufficient for an agent to decide to call it. A minor gap is not documenting any special cases like not-found behavior.

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 schema only defines spec_id as a string with 0% description coverage. The description adds critical semantics by clarifying that this parameter accepts either an id or a slug, which is not implied by the schema alone. It compensates for the schema gap, though it doesn't give format examples or constraints.

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 (Load), a specific resource (one Scenario/Agent Spec), and the selection criteria (by id or slug). It also lists the contents (segments, slots, bindings, workflow_design), clearly distinguishing it from list operations like yaaif_agent_spec_list and from yaaif_agent_get which targets a different entity.

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 a use case—retrieve a single, detailed Agent Spec—but does not explicitly contrast it with alternatives or state when not to use it. There is no mention of when to prefer list or other retrieval tools. The guidance is adequate but not explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It conveys that this is an explicit operator action, but it does not disclose side effects, write semantics, irreversibility, validation failure behavior, or what happens after the backfill is applied. For a mutating apply-style tool, this is a significant gap.

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

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

The description is two short sentences with no filler. The core action is front-loaded, and the second sentence adds a meaningful distinction rather than repeating the tool name or 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 high-risk apply operation with no output schema, no annotations, and zero parameter documentation, this description is not complete enough. It lacks return-value expectations, failure behavior, side effects, and the prerequisite relationship to the preview flow beyond the phrase 'exact preview hash.'

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

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

Schema description coverage is 0%, so the description must compensate for all three parameters. It only adds meaning to 'preview_hash' by describing it as the exact preview hash; it does not explain 'spec_id' or 'expected_version' or how they relate to the backfill operation.

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 action ('Apply') on a specific resource ('legacy-release backfill') and adds a hard qualifier ('with the exact preview hash'). It also explicitly distinguishes itself from tenant rollout automation, which helps separate it from nearby workflow 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?

The description clearly frames this as an operator action for reviewed backfills, and the phrase 'exact preview hash' strongly implies it should follow a preview step. It does not explicitly name the sibling preview tool or list when not to use it, but the context and exclusion are reasonably clear.

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

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

With no annotations provided, the description carries the full burden. It clearly discloses the two most important behaviors: the tool is read-only and it never runs automatically. It does not describe what the preview returns or whether any temporary state is created, but the core safety behavior is transparent.

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

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

The description is two short sentences with no filler. The action is front-loaded in the first sentence, and the critical safety qualifier is in the second. 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?

There are no annotations and no output schema, so the description is the only source of guidance. It omits what the preview output will contain, what normalization means in this context, and how it relates to the sibling apply tool. For an agent to call this correctly and interpret the result, more context is needed.

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 schema provides only `spec_id` as a required string with no description, and schema description coverage is 0%. The description does not explain what `spec_id` refers to, where to find it, or what values are valid. The parameter is somewhat self-explanatory from its name, but the description adds no real semantic value.

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

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

The description names a specific action ('Preview') and a specific object ('legacy release metadata normalization'), so an agent can tell it is a preview operation rather than an apply operation. The phrase 'legacy release metadata normalization' is jargon and not fully explained, which prevents a 5.

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

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

The statement 'This is read-only and never runs automatically for any tenant' gives useful safety context and implies the agent must invoke it explicitly. However, it does not explicitly say when to use this preview instead of the sibling `yaaif_agent_spec_legacy_revision_backfill_apply` or any other alternative.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states it lists scenarios, but does not mention read-only behavior, pagination, default limits, response format, or any side effects. This is minimal and leaves critical behavioral details unspecified.

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

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

The description is a single concise sentence that is front-loaded with the core purpose. It avoids unnecessary verbosity, but is perhaps too terse given the lack of other context.

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 list tool with three parameters and no output schema, the description is inadequate. It does not explain parameter semantics, response shape, or usage context. The agent would need to rely on the schema alone, which is insufficient given 0% description coverage.

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

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

Schema description coverage is 0%, and the description does not mention any of the parameters (q, limit, status) or their meanings. The agent has no indication of how to use these parameters for filtering or pagination, making the tool difficult to invoke correctly.

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 ('List'), a specific resource ('Scenarios (Agent Specs)'), and a scope ('for the active tenant'). It clearly distinguishes from related list tools like yaaif_agent_list (which lists agents) and yaaif_skill_list (which lists skills) by specifying 'Agent Specs'.

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 guidance on when to use this tool versus alternatives, nor any mention of the parameters (q, limit, status) or typical use cases. It does not clarify what scenarios are or how they relate to other agent spec operations, leaving the agent to infer usage.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Query' implies a read operation, but the description does not mention time-windowing behavior, aggregation, result limits, permissions, or what the returned telemetry looks like. The parenthetical '(sessions, tokens, tools)' adds only minor context about metric categories.

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

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

The description is a single front-loaded sentence with no filler or redundant phrasing. It is appropriately concise, though it sacrifices useful behavioral and parameter detail. As a conciseness measure, this is strong.

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

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

With no annotations, no output schema, and only 2 loosely explained parameters, the description should clarify what data is returned and what spec_id and hours mean. It does neither. An agent would likely need to inspect sibling tools or examples to use this correctly, so the description is incomplete for this tool's complexity.

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

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

Schema description coverage is 0%, and the description does not explain the two parameters. spec_id can be loosely inferred as the Scenario identifier from the description and parameter name, but hours is completely unexplained: no units, default, range, or meaning. The description adds no real semantic value beyond what the bare parameter names suggest.

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

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

The description names a specific verb ('Query') and resource ('telemetry metrics attributed to a Scenario') with the metric categories listed in parentheses. This distinguishes it from obvious CRUD siblings like yaaif_agent_spec_get/update/delete, though 'Scenario' is left as a domain term without definition. It is clear enough for an agent to know what the tool does, but not fully differentiated from other telemetry/metrics siblings.

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

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

No guidance is given on when to use this tool versus related tools such as yaaif_ops_telemetry, yaaif_agent_spec_rollout_metrics, or yaaif_telemetry_get. The description implies this is for scenario-attributed metrics, but it provides no exclusions, prerequisites, or context that would help an agent choose between alternatives.

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

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

No annotations are provided, so the description carries the behavioral burden. It communicates that this is an export (non-mutating) action returning a portable document, but it does not specify output format, delivery mechanism, or permissions. This is adequate for a zero-parameter read-style tool, though more detail would help.

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 one concise, front-loaded sentence. It states the action and resource immediately, and 'portable' plus 'review or promotion across environments' add meaningful context without padding.

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

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

For a zero-parameter tool with no annotations and no output schema, the description covers the essential purpose and what is produced. It could be more explicit about what 'portable' means or how the export is returned, but an agent can still select and call this tool correctly.

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

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

The input schema has zero parameters, so there are no parameter semantics for the description to clarify. The baseline of 4 applies because nothing is missing in parameter documentation.

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

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

The description uses a specific verb ('Export') on a specific resource ('Scenario tenant policy document') and adds a clear purpose ('for review or promotion across environments'). It distinguishes this from nearby policy and release tools by emphasizing 'portable' and cross-environment use.

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 provides clear context for when this tool is relevant—review or promotion across environments—so an agent can match it to the user's intent. It does not explicitly name alternatives or exclusion conditions, but the context is sufficiently 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool is read-only ('Read') and provides a default behavior for new tenants ('New tenants default to observe'), which helps the agent understand the state it might encounter. This is valuable context beyond the name. However, it does not disclose potential side effects like caching or rate limits, but for a simple getter, this is sufficient.

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

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

The description is a single concise sentence that states the primary action and a key detail about default behavior. It is front-loaded with the verb and resource, and every word earns its place. There is no fluff, and it is appropriately brief for a zero-parameter getter.

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

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

For a tool with no parameters, no output schema, and no annotations, this description is fully complete. It tells the agent exactly what it does (reads the mode), what the default is (observe), and implies the return type (the mode value). There is nothing else an agent needs to know to invoke it correctly. The simplicity of the operation makes this sufficient.

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

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

The input schema has zero parameters, and schema description coverage is 100% (vacuously true). Since there are no parameters to document, the description doesn't need to add parameter semantics. The description focuses on the return value (the enforcement mode) and default behavior, which is the only meaningful semantic content. A score of 4 is appropriate because the description effectively 'documents' the return value, which is the only relevant semantic aspect.

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 clearly states it reads the tenant Scenario enforcement mode, with a specific verb ('Read') and resource ('tenant Scenario enforcement mode'). It also provides a useful default behavior ('New tenants default to observe'), which clarifies the tool's purpose without ambiguity. This distinguishes it from sibling tools like yaaif_agent_spec_policy_set and yaaif_agent_spec_policy_import, which are mutating or importing operations.

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 a read-only operation but does not explicitly state when to use this tool versus alternatives. For example, it doesn't mention when to use yaaif_agent_spec_policy_get instead of yaaif_agent_spec_policy_export or yaaif_agent_spec_policy_set. The context of 'Read the tenant Scenario enforcement mode' is clear, but there is no explicit guidance on when not to use this tool or when to prefer a sibling. Without annotations, this is a minor gap.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only states what the document controls, not what importing does (e.g., overwrite, validate, require existing policy) or any side effects. It also misleads by claiming 'version-1' while the schema permits version 2.

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 with the main action and resource front-loaded. The description is efficient, though the inaccurate 'version-1' qualifier slightly harms precision.

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 a complex union input schema, no output schema, and no annotations. This brief description omits validation behavior, merge/overwrite semantics, return values, and version reconciliation, making it inadequate for confident invocation.

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 description adds meaning by linking the document to enforcement, evidence TTL, and high-assurance approval, which maps roughly to mode, evidence_ttl_days, and require_second_approver. However, with 0% schema description coverage, it does not explain the version 1 vs 2 structural differences or the additional release governance fields.

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

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

Clearly identifies the action (import) and resource (a Scenario tenant policy document), and states what the document controls. However, it does not differentiate from the sibling yaaif_agent_spec_policy_set, and the 'version-1' qualifier conflicts with the schema that also accepts version 2.

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

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

No guidance is given on when to use this tool versus alternatives such as yaaif_agent_spec_policy_set or yaaif_agent_spec_policy_export. No prerequisites, exclusions, or decision criteria are mentioned.

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

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

No annotations are present, so the description must carry the burden of behavioral disclosure. It implies a mutation (promote) but does not disclose side effects, reversibility, impact on other tenants, or any authorization requirements. The phrase 'from observe to warn or require' is misleading because the tool can also set to 'observe', contradicting the described promotion direction.

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

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

The description is a single concise sentence with no fluff, which is good for structure. However, it is under-specified, providing minimal information that could have been expanded without verbosity. It is not tautological but sacrifices clarity for brevity.

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 a simple schema, but with no output schema, no annotations, and a very short description, critical context is missing. The agent does not learn what 'adoption inventory review' is, what the policy modes mean, or what the consequences of promotion are. The description is insufficient for a safe and correct invocation.

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

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

Schema coverage is 0%, and the description does not mention the 'mode' parameter at all. While the enum values are listed in the schema, the description only hints at 'warn' and 'require' and gives no explanation of what each mode means or how to choose one. The agent receives no semantic guidance beyond the enum names.

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

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

The description states a specific verb ('promote') and resource ('active tenant') and implies a policy state change. It distinguishes from get/import/export siblings by the 'promote' action. However, it says 'from observe to warn or require' while the schema allows setting to 'observe' as well, creating a slight inaccuracy about the full scope.

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

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

Only a vague timing context is given ('after adoption inventory review'), with no explicit when-to-use versus alternatives like yaaif_agent_spec_policy_get or import/export. No exclusions or conditions are provided, leaving the agent to infer when this tool is appropriate.

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

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

No annotations are provided, so the description carries the full burden. It indicates a read operation ('Get') but discloses no behavioral traits such as required permissions, failure modes, or what exactly is returned. The mention of 'lifecycle status' is superficial and doesn't explain side effects or limitations.

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

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

The description is a single, compact sentence with no wasted words. It front-loads the action and states the target. It is efficient, though its brevity contributes to its incompleteness in other dimensions.

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?

This is inadequate for a tool with no output schema, no annotations, and zero parameter documentation. An agent cannot determine what spec_id refers to, what 'processing status' includes, or how to interpret the result. The description is far too sparse to support correct invocation.

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 0% schema description coverage, the description must explain the parameter. It does not mention spec_id at all. The parameter is only defined as a string in the schema, and the description adds no meaning about what spec_id represents or how it should be formatted.

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 clear verb ('Get') and a resource ('Scenario processing / lifecycle status'), and lists some aspects (revisions, sync, attribution). However, 'Scenario processing / lifecycle status' is vague and not clearly differentiated from other agent spec tools like yaaif_agent_spec_get or yaaif_agent_spec_revisions. It's not a tautology, but lacks precision.

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

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

No guidance is provided on when to use this tool versus the many sibling tools with similar names (e.g., yaaif_agent_spec_revisions, yaaif_agent_spec_sync_preview). There is no mention of conditions, alternatives, or context that would help an agent select this tool appropriately.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions 'immutable' as a key trait, implying that published releases cannot be modified. However, it does not disclose other behaviors such as permission requirements, whether publishing is destructive (e.g., overwriting), side effects, or the nature of the response. This is a significant gap for a release-publishing action.

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

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

The description is a single, well-structured sentence that fronts the primary action and then provides versioning guidance. It is concise and free of fluff. However, it is so brief that it under-covers necessary details, but the conciseness itself is appropriate for the content it does convey.

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

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

For a tool with 5 parameters, no output schema, and no annotations, the description is woefully incomplete. It omits critical information about the expected_version (likely a concurrency guard), change_summary, and release_channel, and does not describe the outcome or side effects of publishing. An agent cannot reliably use this tool correctly without additional context.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameter meanings. It only explains release_kind values (patch/minor/major) and their rationale. It does not clarify the purpose of spec_id, expected_version, change_summary, or release_channel, leaving the agent to infer them from names alone. This is insufficient for a 5-parameter tool with no schema documentation.

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 ('Publish') and resource ('immutable semantic Scenario release'), which makes the tool's core function clear. It also hints at versioning semantics (patch/minor/major) that distinguish it from mere creation or updates. However, it does not explicitly contrast with sibling tools like export/import, though the term 'publish' is fairly distinguishing.

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 explicit guidance on when to use each release_kind: 'Use patch for corrections, minor for compatible capability additions, and major for breaking architecture or requirement changes.' This is clear parameter-level usage advice. It does not mention when not to use the tool or alternatives, but the guidance is actionable and sufficient for the primary decision.

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

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

With no annotations, the description must carry the behavioral burden; it does signal a read operation ('Return') and an output format ('machine-readable'), and it enumerates the returned categories. However, it does not disclose whether computing readiness has side effects, what inputs/state are required (e.g., published spec), or how 'stale' evidence is determined.

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

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

The description is a single front-loaded sentence with no filler; every phrase adds information about what the returned readiness report contains. It is appropriately sized for a one-parameter read 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?

The tool is an aggregate report of four distinct concern areas, and there is no output schema or annotation to fill gaps. The description does not define the machine-readable structure, how the categories are computed, or what spec_id identifies, so an agent cannot fully predict the response or prerequisites.

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

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

The input schema provides only a required spec_id string with 0% description coverage, and the tool description never mentions spec_id or explains what values it accepts. Although the tool name makes the parameter's role somewhat inferable, the description fails to compensate for the schema's lack of documentation.

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

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

The description uses a specific verb ('Return') and a precise resource ('agent spec readiness'), enumerating four output categories: activation/publish blockers, requirement coverage, stale evidence, and pending sync conflicts. It is not a tautology, but it does not explicitly distinguish itself from close siblings such as yaaif_agent_spec_coverage and yaaif_agent_spec_conflicts.

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

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

No guidance is provided about when to call this tool rather than the overlapping agent_spec_* siblings. The description never names alternatives, exclusions, or conditions, leaving the agent to infer that 'readiness' is a summary of coverage/conflicts.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the data source (approval-service) and intent (refresh), but does not say whether the refresh mutates state, is idempotent, or how stale or missing approvals are handled.

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

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

The description is a single tight sentence with the core directive front-loaded and no filler. It is concise without sacrificing the key temporal context.

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 simple two-parameter refresh operation, the description provides the essential trigger and resource. However, since there are no annotations and no output schema, it leaves unclear what 'governed action' means, what the caller should do with the refreshed approval, and what kind of response to expect.

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

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

Schema description coverage is 0% and the description does not explain spec_id or approval_id. The parameter names are somewhat self-explanatory and the phrase 'one...approval' hints at approval_id, but the description adds essentially no meaning beyond the raw 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 states a specific action ('Refresh'), a specific resource ('one Scenario release approval'), and a workflow context ('before attempting the governed action'). It is distinguishable from siblings like release_approval_request and release_approvals because it emphasizes a refresh step, though 'Scenario' and 'governed action' are not defined precisely.

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 a clear temporal trigger for when to use the tool: before attempting a governed action. This is useful context, but it does not explicitly name alternatives or state when not to use the tool, so it stops short of full 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the policy requirement but does not disclose side effects, whether the request is asynchronous, idempotency handling, or what happens after the request (e.g., creates an approval task). The description only says 'request review' without behavioral details.

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 short and front-loads the purpose, but the second sentence is a caveat. It is concise but lacks necessary detail; however, it is not verbose and has a clear structure.

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

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

For a tool with 7 parameters (3 required) and no output schema or annotations, the description is severely incomplete. It fails to explain parameter meaning, expected outcomes, failure conditions, or the relationship to other approval-related tools. An agent would struggle to call this correctly without additional context.

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 description does not explain any of the 7 parameters. Schema description coverage is 0%, and the description gives no hints about spec_id, expected_version, action semantics, release_kind, restore_revision, candidate_revision, or idempotency_key. The mention of scenarios doesn't map to parameters, so the description adds no value beyond the bare 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 clearly states the tool requests approval-service review for three scenarios (major release, release-candidate promotion, restore), distinguishing it from direct publish/restore tools. However, the mapping between the described scenarios and the action enum (only 'publish' and 'restore') is ambiguous – 'release-candidate promotion' isn't directly represented, so the purpose is clear but not fully precise.

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 provides a prerequisite condition ('inactive unless tenant policy v2 explicitly enables release governance') but does not explicitly contrast with sibling tools like yaaif_agent_spec_publish, yaaif_agent_spec_release_candidate_promote, or yaaif_agent_spec_revision_restore. It implies this is for approval workflow, but doesn't state when to choose this over direct action tools.

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

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

With no annotations, the description carries the behavioral disclosure burden. It states the tool lists requests and status, implying a read-only operation, but does not explicitly confirm no side effects, discuss potential latency, or mention any limitations. It gives some context (immutable-draft, latest status) but does not go beyond the basic function.

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

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

The description is a single, concise sentence that leads with the action and object. There is no fluff or redundancy; every word contributes to the meaning. It is appropriately front-loaded and efficient.

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 single required parameter and no output schema, the description should clarify what spec_id represents and what the returned data structure looks like. It does neither. The parameter is ambiguous, and the return format is unstated, leaving an agent with insufficient information to call the tool correctly.

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

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

Schema coverage is 0% and the description does not explain what 'spec_id' refers to. The description mentions 'immutable-draft release approval requests' but never connects that to the parameter. An agent has no clue what value to pass for spec_id, making the tool unusable without external knowledge. This is a critical gap.

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

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

The description clearly states a specific action ('List') and resource ('immutable-draft release approval requests') and adds that it returns the latest recorded approval-service status. It distinguishes from siblings like yaaif_agent_spec_release_approval_request (create) and yaaif_agent_spec_release_approval_refresh (refresh). The verb and object are precise, leaving no ambiguity about the tool's function.

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 a read-only listing operation but does not explicitly mention when to use it versus alternatives or any exclusions. It lacks direct guidance on when not to use it, but the purpose is clear enough for an agent to infer the context. No explicit alternatives are named, so it falls short of the highest bar.

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

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

With no annotations provided, the description carries the full burden. It explicitly discloses that promotion creates a new immutable record and never rewrites the candidate, which is valuable behavioral context. However, it omits side effects like whether approvals are required, what happens to existing stable versions, or error conditions.

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 concise sentences with no fluff, front-loaded with the primary purpose. The behavioral note is efficiently integrated.

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

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

Given the tool's complexity (4 parameters, no output schema, no annotations), the description is incomplete. It lacks parameter explanations, preconditions like what 'verified' means, and any mention of return values or failure modes. An agent would need to infer too much.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain any of the parameters (spec_id, revision, change_summary, expected_version). The names and required fields hint at their purpose, but without explicit definitions, an agent may not correctly map values.

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 clearly states the action (promote), the resource (verified Scenario release candidate), and the target (stable SemVer release). It also distinguishes itself by noting it creates a fresh immutable record and never rewrites the candidate, which sets it apart from related promotion or publishing 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?

The description implies the tool is for verified candidates and creates a stable release, but it does not explicitly state when to use it versus alternatives like yaaif_agent_spec_publish or other release tools. There is no exclusion or direct comparison to siblings.

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

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

No annotations are present, so the description carries the behavioral disclosure burden. 'Preview' suggests a non-mutating inspection and 'policy may optionally block required incompatibilities' exposes a conditional policy effect, which is useful context. However, the description never clarifies whether 'block' is an output flag or an actual enforcement action, whether the call has side effects, or what the return value 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?

The description is a single dense sentence with the verb and object front-loaded, and it contains no filler. 'May optionally' is mildly redundant, and the heavy jargon reduces readability, but the structure is compact and appropriate.

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

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

With no output schema and no annotations, the description needs to provide more of the operational contract, but it omits return-value expectations and the practical meaning of 'blocked.' For a policy-aware compatibility preview, the missing side-effect and output semantics are material gaps.

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

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

Schema description coverage is 0%, and the description does not explicitly explain either parameter. 'Provider semantic release' hints at the meaning of release_kind, but spec_id is completely undefined, so an agent cannot tell what entity it references or how release_kind changes the compatibility check.

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

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

The description uses a specific verb ('Preview') and identifies the resource ('declared dependent-Scenario compatibility') plus the release context ('proposed provider semantic release'), so the basic operation is recognizable. It does not explicitly differentiate itself from sibling release/adoption tools, and the domain jargon is left unexplained, which lowers the score slightly.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no sibling alternatives are mentioned. The phrase 'with a proposed provider semantic release' implies the natural pre-release compatibility-checking context, but an agent must infer whether this is preferable to yaaif_agent_spec_adoption_preview or the release approval/promotion tools.

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

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

With no annotations, the description carries the full burden. The verb 'List' and the qualifier 'declared' imply a read-only, non-mutating operation, which is useful. However, it does not disclose potential errors, auth requirements, or whether an empty result is possible.

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 sentence with no filler. The core action and key qualifiers ('explicit', 'provider', 'version constraints', 'consumer Scenario') are front-loaded and every word contributes meaning.

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?

This is a simple one-parameter read operation, so the description is not severely inadequate. Still, with no output schema and no explanation of what a 'version constraint' contains or how the result is presented, the agent has limited context for interpreting the response.

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 schema has a single parameter, spec_id, with 0% description coverage. The description refers to 'this consumer Scenario' but never explicitly connects it to spec_id, leaving the agent to infer that spec_id identifies the consumer Scenario whose dependencies should be listed.

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?

Description states a specific verb ('List') and a clear resource: explicit provider Scenario version constraints declared by the consumer Scenario. This distinguishes it from generic dependency tools and makes the tool's scope immediately understandable.

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

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

No guidance on when to use this tool versus alternatives. Sibling tools such as yaaif_agent_spec_dependencies, yaaif_agent_spec_release_dependency_upsert, and yaaif_agent_spec_release_dependency_delete exist, but the description does not explain how this listing tool differs or when each should be preferred.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the optimistic concurrency aspect ('current optimistic draft version'), implying a version-check behavior via expected_version. However, it does not mention that this is a destructive delete operation, nor any side effects like what happens if the dependency isn't found or if the version mismatches. It provides only minimal transparency.

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?

Single sentence, front-loaded with the action and resource, zero redundancy. It is appropriately concise for a simple delete operation.

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, no annotations, and three required parameters, the description is insufficiently complete. It does not explain parameter meanings beyond the version hint, does not describe any return value or error behavior, and offers no usage context compared to sibling operations. An agent would need additional information 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 0%, so no parameter info exists in the schema. The description partially clarifies expected_version ('current optimistic draft version') but gives no explanation for spec_id or provider_spec_id, which are left to the agent to infer. The description does not fully compensate for the lack of parameter documentation.

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

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

The description uses the specific verb 'Remove' and identifies the resource ('explicit Scenario provider dependency') and the context ('using the current optimistic draft version'). This is clear and distinguishes it from sibling tools like dependency_upsert (add/update) and dependencies (list/list view).

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

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

No guidance is given on when to use this tool versus alternatives, nor any prerequisites or conditions. The description does not explain when a delete is appropriate or when to use upsert instead, leaving the agent to infer usage purely from the 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?

With no annotations present, the description carries the behavioral burden. It contributes 'The update is version-protected and explicit,' hinting at an optimistic concurrency check via expected_version, but does not disclose failure modes, side effects, or permissions. This is partial transparency, not a complete behavioral profile.

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

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

The description is two sentences with no filler: the first gives the core purpose and the second adds a distinctive behavioral trait. It is appropriately sized and every phrase 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?

This is an upsert tool with five parameters, no annotations, no output schema, and zero schema descriptions. The description omits parameter meanings, the version-protection mechanism, the expected format of version_constraint, and whether required is optional. An agent cannot safely know how to invoke it correctly from the description alone.

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

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

Schema description coverage is 0%, so the description must compensate. It only obliquely references a release range (likely version_constraint) and version protection (likely expected_version), but never explains spec_id, provider_spec_id, version_constraint syntax, or the required boolean. This is inadequate for constructing a valid call.

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 clearly states the action ('Declare') and the resource (consumer Scenario depends on provider Scenario release range), which distinguishes it from listing or deleting dependencies. However, it does not explicitly differentiate from siblings like yaaif_agent_spec_release_dependencies, relying on the tool name's 'upsert' to imply create-or-update.

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

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

The description gives no guidance on when to use this tool versus alternatives such as yaaif_agent_spec_release_dependency_delete or yaaif_agent_spec_release_dependencies. It does not state prerequisites, when to create versus update, or what makes it the right choice in a given workflow.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but it only adds 'signed-by-hash' and an intended use case. It does not disclose whether the operation is read-only, what the returned manifest contains, how it is delivered, or what failures can occur.

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

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

The description is a single focused sentence that front-loads the action ('Export') and includes the most important qualifier ('signed-by-hash'). There is no filler or redundant repetition of the tool name.

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

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

For a tool with no annotations, no output schema, and low schema coverage, the description is too thin. It omits output format, side effects, prerequisites, and relationships to nearby release-management tools, leaving several important operational details 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 0%, so the description must compensate for the lack of parameter documentation. It does not mention spec_id or revision at all, leaving the agent to infer their meaning from names alone. The schema only provides types, not semantic guidance.

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

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

The description names a specific operation ('Export') and a specific resource ('signed-by-hash Scenario release manifest'), so an agent understands the basic action. It does not explicitly differentiate from sibling release tools like yaaif_agent_spec_release_provenance_record or yaaif_agent_spec_release_import, but the export/import contrast is reasonably inferable.

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

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

The phrase 'suitable for committing to Git, review, and disaster recovery' gives a clear use context. However, it does not state when to prefer this tool over related release tools, nor does it mention prerequisites such as a published/released spec or when not to use it.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It does disclose important non-destructive behavior: creates a draft, preserves slot identities, and never changes release history. However, it omits details about permission requirements, version-mismatch behavior, validation failures, or whether the import is idempotent.

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, both informative, with the core purpose front-loaded and the key invariants stated immediately after. No filler or repetition of schema details.

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 four parameters, a nested required document object, no output schema, and no annotations, so the description needs to do more. It fails to explain how expected_version is used, what 'from Git' means in terms of the spec_id parameter, what change_summary is for, or what the resulting draft looks like. The description provides a good summary but not enough operational context for a correct call.

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

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

Schema description coverage is 0%, so the description must compensate for the four parameters, but it provides no parameter-level meaning. There is no explanation of what spec_id refers to, how expected_version is validated, what the nested document must contain, or what change_summary is for. The agent is left to infer all of this from the schema structure 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?

The description names a specific verb (import), a specific resource (reviewed, hash-verified Scenario release manifest from Git), and the outcome (a new draft). It also states the two defining invariants: preserving bound slot identities and never changing release history. This clearly distinguishes the tool from export, promote, provenance, and other release-related siblings.

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 clear context: use this when importing an already reviewed and hash-verified release manifest as a draft. However, it does not explicitly say when not to use it or name alternatives such as release_candidate_promote, release_export, or adoption tools. The usage is implied rather than explicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. 'List' implies a read-only operation, and the description names the provenance categories, but it does not mention authentication needs, pagination, return format, or whether empty results are possible. The 'immutable Scenario releases' detail adds useful context but is not a complete behavioral profile.

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

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

The description is a single, front-loaded sentence with no filler. It states the operation and the resource scope efficiently, making it easy for an agent to parse quickly.

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

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

Given the low complexity (one required parameter, no nested objects, no output schema), the description is adequate but has gaps. It does not describe the shape of the returned provenance data, pagination behavior, or any filtering options beyond the implicit spec_id. This is acceptable for a simple list tool but not fully 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 0%, and the description does not explain the meaning of the sole required parameter, spec_id. While the parameter name is somewhat self-explanatory, the description does not compensate for the schema gap by specifying what kind of ID spec_id is or how it relates to 'Scenario releases'.

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

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

The description uses a specific verb ('List') and a specific resource ('build/test/artifact/SBOM/deployment provenance attached to immutable Scenario releases'). This clearly distinguishes it from sibling tools like yaaif_agent_spec_release_provenance_record, which is about recording rather than listing provenance.

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 the tool is used when provenance for Scenario releases is needed, but it provides no explicit when-to-use guidance, exclusions, or alternatives. It does not mention that provenance can be recorded via a sibling tool or when listing would be inappropriate.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states that provenance is 'recorded,' implying a write operation, but does not mention any side effects, idempotency, validation behavior, or what happens to the release state if recording fails. The note about promotion requirements is a precondition, not a behavioral description. For a mutation tool with no annotation coverage, this is a significant gap.

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

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

The description is concise and front-loaded: the core action and resource are in the first sentence, and the supporting context (promotion requirement) is in a short second sentence. There is no wasted wording. It earns a 4 because, while efficient, it could be improved by integrating parameter hints or usage exclusions into the structure without becoming verbose.

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

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

For a tool with 11 parameters, 4 required, no schema descriptions, no output schema, and no annotations, the description is critically under-specified. It fails to explain any parameter semantics, does not describe the return value or effects, and lacks examples or edge-case guidance. The agent cannot reliably construct a valid invocation from this description alone. This is a major completeness 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 0% (no descriptions in the schema), and the description does not explain any of the 11 parameters. It lists the kinds of provenance (which map to the 'kind' enum) but provides no meaning for spec_id, expected_version, revision, result, payload, or other fields. The description adds no semantic value over the raw schema, so the agent cannot understand what each parameter is for. This is severely inadequate.

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 clearly states the tool's verb ('Record') and resource ('provenance for one immutable Scenario release'), and enumerates the specific types of provenance (build, isolated verification, artifact, SBOM, deployment). It distinguishes this recording tool from the sibling listing tool (yaaif_agent_spec_release_provenance_list) by its action. The added note about promotion requirements provides useful context without ambiguity.

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 a conditional hint: 'A release candidate needs passing verification provenance before promotion,' which implies when verification provenance should be recorded. However, it does not explicitly compare against alternatives (e.g., evidence_record) or state when NOT to use this tool. The usage guidance is partial—enough to infer the main use case, but without clear exclusions or differentiation from related record/evidence tools.

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

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

No annotations are provided, so the description carries full behavioral disclosure burden. The description mentions 'immutable' releases, implying a read-only comparison, but it does not explicitly state that the tool has no side effects, nor does it describe the output format or behavior on mismatch. Critical details about whether this is a safe read operation are missing.

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

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

The description is a single, well-structured sentence with no fluff. It front-loads the action ('Compare'), the object ('two immutable Scenario releases'), and the scope ('at the identity, segment, requirement, and slot level'), efficiently conveying the core purpose.

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

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

Given the complexity of comparing at four distinct levels, the lack of an output schema, and no annotations, the description is inadequate. It does not explain what kind of differences will be reported, how to interpret the results, or any prerequisites (e.g., both revisions must exist). An agent would struggle to correctly use this tool without more context.

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

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

Schema description coverage is 0%, and the description does not explain what spec_id, from_revision, or to_revision mean beyond implying a 'from' and 'to' comparison. The description references 'two ... releases' but does not map them to the parameters, leaving the agent to guess which revision is which and what spec_id refers to.

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 clearly states the tool compares two immutable Scenario releases at the identity, segment, requirement, and slot level. It also positions the tool relative to downstream actions ('before restoring or promoting'), which distinguishes it from sibling tools like revision_restore and release_candidate_promote.

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 explicitly states the comparison is done 'before restoring or promoting a change,' giving clear context for when to invoke it. However, it does not explicitly name the alternative tools (e.g., yaaif_agent_spec_revision_restore) or state when NOT to use this tool, leaving some inference to the agent.

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

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

With no annotations, the description carries the disclosure burden. It explicitly guarantees historical releases are never altered and notes that the restored draft is not automatically published. It doesn't explain concurrency or conflict behavior, but the core behavioral contract is clear.

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 dense, front-loaded sentence; every phrase earns its place and no filler or restatement.

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?

Without annotations or an output schema, the description needs to cover the required parameters and success/failure semantics. It leaves expected_version's meaning and the operation's return value or conflict behavior to guesswork.

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

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

Schema description coverage is 0% and the description does not explain any parameter. spec_id and revision are somewhat inferable, but expected_version is functionally ambiguous (target version vs optimistic concurrency check) and change_summary is not mentioned at all.

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: restore a Scenario release into a new draft. It also clarifies the core invariant ('Historical releases are never altered'), which distinguishes it from publish, compare, or promote siblings.

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 clear usage context: use this when you need a mutable draft from an immutable release, then review and publish it. It does not explicitly name alternative tools or list when-not conditions, so it stops one step 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 are absent, so the description must disclose behavioral traits. It notes the data is 'immutable', implying a read-only operation, but does not explicitly state that this is a non-mutating list operation, nor does it mention pagination, limits, ordering, or authorization requirements. The description carries insufficient behavioral 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?

The description is a single efficient sentence that front-loads the core purpose and enumerates the returned fields. It is concise, though it could be better structured with explicit parameter context.

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

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

Given the large sibling set, no output schema, and no annotations, the description is far from complete. It does not explain the relationship to other spec tools, does not define spec_id, and lacks any indication of output format or call constraints. An agent would have difficulty selecting and invoking this tool correctly.

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

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

With schema description coverage at 0%, the description must clarify the purpose of spec_id. It does not; it never mentions that spec_id identifies the scenario whose revisions are to be listed. The parameter's meaning is entirely opaque.

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 clear verb (list) and a specific resource ('immutable Scenario releases') and enumerates the fields returned (SemVer, parent revision, content hash, change summary, author). It is more informative than the tool name alone and likely refers to listing revisions of a given agent spec, though the term 'Scenario' is ambiguous and could be confused with other spec-related tools like yaaif_agent_spec_list.

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

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

No guidance is provided on when to use this tool versus the many related siblings (e.g., yaaif_agent_spec_list, yaaif_agent_spec_get, yaaif_agent_spec_release_provenance_list). There is no mention of prerequisites, typical use cases, or exclusions.

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

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

With no annotations, the description must fully disclose behavior. The verb 'Read' implies a non-mutating operation, which is helpful, but there is no mention of scoping (e.g., which agent spec or rollout), output format, or any required state (e.g., needing an active rollout). The five metric names hint at output content but not at any behavioral caveats.

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

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

The description is a single, front-loaded sentence that leads with the action verb and resource, then enumerates the metric types in a compact series. Every word adds value and there is 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?

For a zero-parameter read-only tool, the description covers the core functionality but leaves gaps: it doesn't clarify whether the metrics are global or scoped to a specific agent spec, what form the output takes (JSON structure, aggregation, time range), or any caveats about data freshness. These are not severe, but an agent could call it with incorrect assumptions about scope.

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 has 0 parameters oz, so the baseline is 4 per rubric. The description does not need to compensate for missing schema details because there is nothing to invoke with. It accurately implies the tool takes no arguments by having no parameter discussion and an 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 uses the specific verb 'Read' and identifies a clear resource ('observe/warn/require rollout metrics') followed by five concrete metric categories. This is more specific than a tautology, but it doesn't contrast with sibling tools like yaaif_agent_spec_metrics or yaaif_agent_spec_coverage, so it relies on the name to carry differentiation.

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

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

No guidance is provided on when to use this tool over any of the ~200 siblings. It does not mention alternative tools, prerequisites, or typical scenarios. The description only states what it reads, leaving an agent to guess whether this is the right tool for a given intent.

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

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

No annotations are present, so the description carries the full burden. It does disclose the two concrete behaviors: to_objects writes the Scenario onto bound catalog objects, and from_objects adopts live drift into the Scenario. However, it omits side-effect/irreversibility context, expected_version conflict behavior, and what happens if the preview is stale.

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 compact sentence, front-loaded with the action, then a clean semicolon-separated mapping of the two directions. Every clause 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 four required parameters, no output schema, and no annotations, this is under-specified for an apply/commit tool. The agent is not told how expected_version controls the apply, how to obtain a reviewed preview_id, or how this fits with sync_preview and the direct sync operations.

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

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

Schema description coverage is 0%, so the description must compensate, but it only clarifies the direction enum values. spec_id and preview_id are left to naming convention, and expected_version's role is completely unexplained despite being a required integer with exclusiveMinimum.

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 concrete action ('Apply a reviewed preview') and a resource, and the semicolon clause explains both directions (to_objects/from_objects), so the agent knows what the tool does. It doesn't explicitly distinguish this from sibling sync_from_objects/sync_to_objects tools beyond the preview/apply framing.

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?

'Apply a reviewed preview' clearly implies a prerequisite: the preview must already be reviewed before this tool is called. However, it does not name alternatives or explicitly state when NOT to use this tool versus sibling tools like yaaif_agent_spec_sync_preview or the direct sync tools.

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

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

With no annotations provided, the description carries the full burden. It discloses the destructive behavior (overwrites) and mentions preview as a safety step. However, it doesn't cover reversibility, permission requirements, or failure modes, which would be expected for a mutation tool without annotation support.

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 concise sentences that get to the point, front-loading the purpose and then adding usage guidance. No fluff, but the structure could be slightly improved by separating the overwrite warning from the preview instruction.

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

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

For a tool with three required parameters and no output schema, the description is sparse. It mentions preview but doesn't explain how to obtain preview_id or what expected_version is for. Missing parameter meanings and return behavior make it incomplete for an agent to call correctly without external knowledge.

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

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

Schema description coverage is 0%, and the description provides no information about spec_id, expected_version, or preview_id. Parameter names are somewhat self-explanatory, but the description adds no semantics and fails to compensate for the missing schema descriptions.

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 clearly states it adopts live catalog objects into the Scenario and overwrites Scenario-owned names and workflow graphs. It names a sibling (yaaif_agent_spec_sync_preview) for preview, which helps differentiate, though it doesn't explicitly mention the reverse-direction sibling (sync_to_objects). The verb 'Adopt' and resource are specific enough.

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 instructs to preview with yaaif_agent_spec_sync_preview before applying, and notes it is not the default finish step after create/bind. This gives actionable guidance on when to use it, though it doesn't contrast with all related tools like sync_to_objects or adopt.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Read-only' and the required ordering, which are valuable, but it does not describe what the preview returns, whether changes are guaranteed to be absent, or any limitations.

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

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

The description is two short sentences with no filler. The core action and directions are front-loaded, and the read-only/ordering note is placed efficiently at the end.

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 simple two-parameter preview tool, the description covers the purpose, direction semantics, safety, and sequencing. The lack of an output schema and any return-format detail is a minor gap, but the essential information needed to call the tool correctly 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 0%, so the description must compensate. It does so well by explaining the meaning of both enum values ('to_objects: spec → catalog', 'from_objects: catalog → spec'), which adds real semantic value beyond the raw schema. spec_id remains only nominally explained, but the directional mapping clarifies its role.

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 clearly states the tool previews 'apply' or 'adopt' operations and precisely maps directions to spec→catalog or catalog→spec. It distinguishes itself from the related sync_apply tools by emphasizing preview and read-only, though it does not explicitly name alternative preview tools like adoption_preview.

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 provides clear context: use this to preview before a sync apply, and it is read-only. It does not explicitly list exclusions or contrast with sibling tools, but the ordering constraint 'must precede sync apply' gives actionable usage 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?

With no annotations provided, the description carries the full burden for behavioral disclosure. It does state one important safety behavior: 'Skill pack files are not overwritten.' However, it does not disclose other effects, such as whether existing catalog object names are replaced, reversibility, permission requirements, or conflict handling—critical for a mutation tool with zero 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?

The description is three sentences with no filler. The first sentence states purpose, the second gives the precise workflow (preview then apply), and the third adds a critical safety caveat. Information is front-loaded and 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?

For a mutation tool with no annotations, no output schema, and 0% parameter coverage, the description must carry substantial explanatory weight. At 3 sentences, it leaves major gaps: what 'bound catalog objects' are, how to obtain preview_id, the meaning of expected_version, and what happens on failure. It provides some high-level context but is far from complete for correct invocation.

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

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

The input schema provides no parameter descriptions (0% coverage), and the description does not compensate. It never explains what spec_id, preview_id, or expected_version represent, how preview_id is obtained (beyond mentioning the preview tool), or what expected_version enforces. An agent cannot infer the meaning of these required parameters from the description 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?

The description clearly states a specific verb ('Apply') and resource ('Scenario-owned names and workflow_design onto bound catalog objects'), and it references the preview tool with the direction '(to_objects)', distinguishing it from from_objects. However, it does not explicitly contrast with the sibling 'yaaif_agent_spec_sync_apply', which could be ambiguous for an agent deciding between the two.

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 explicit sequencing: 'Preview with yaaif_agent_spec_sync_preview (to_objects), then apply.' This tells the agent when to use this tool relative to the preview step. It lacks when-not-to-use guidance and does not mention alternatives like sync_from_objects, but the core usage context is clear.

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

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

With no annotations, the description carries the full burden. It discloses the mutating nature via 'Copy' and 'explicit adopt of live graphs,' implying a directed overwrite of the workflow_design segment. However, it omits permissions, version-check behavior, side effects, and reversibility, leaving only partial transparency.

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 concise sentences with no redundancy. The core action is front-loaded, and the alternative sibling is referenced immediately after clarifying the operation's semantic, making every word earn 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?

For a niche sync tool with no annotations and no output schema, the description covers the high-level action and sibling differentiation, but not enough for an agent to call it confidently. It lacks parameter semantics, return value expectations, and details about how expected_version is used, leaving meaningful gaps.

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

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

Schema description coverage is 0%, and the description does not mention spec_id or expected_version at all. The parameter names offer some inherent meaning, but the description adds no value beyond the schema and fails to compensate for the lack of parameter documentation.

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 operation: copying bound ambient workflow graphs into the Scenario workflow_design segment, and clarifies it as an explicit adopt of live graphs. It also distinguishes directionality from the sibling yaaif_agent_spec_sync_to_objects by naming what that alternative does, making the tool's unique role clear.

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 explicitly says to prefer yaaif_agent_spec_sync_to_objects when applying Scenario-owned workflow_design onto catalog objects, giving an alternative with a clear condition. It does not enumerate other scenarios or edge cases where this tool should not be used, but the primary routing is handled well.

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

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

No annotations provided, so the description must convey behavior. It mentions the rejection behavior for Active, but does not disclose other validation rules (e.g., allowed transitions, handling of expected_version mismatch) or side effects. It is not contradictory, but leaves the agent guessing about error conditions.

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 concise sentence packs the purpose and a key constraint. It is front-loaded with the verb and resource. Could be slightly clearer with a second sentence on parameters, but it is appropriately short.

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 state transition tool with no output schema and no annotations, more detail is needed. It covers the special Active case but not the general transition rules (e.g., which transitions are legal, what happens on conflict). The expected_version parameter hints at concurrency, but the description doesn't confirm that, leaving room for misuse.

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

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

Schema coverage is 0%, so the description should explain parameters. It does not describe spec_id, expected_version, or status semantics beyond what the schema enum shows. It adds the lifecycle context but fails to explain the purpose of expected_version (optimistic locking) or the allowed status values' meaning.

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 it 'Transitions a Scenario lifecycle state', which is a specific verb and resource. It also hints at a key constraint (Active rejected until readiness passes), but lacks differentiation from the many sibling state-related tools such as activation_override or adopt.

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 a clear rule: 'Active is rejected until readiness passes; use a separately authorized override only for exceptional cases.' This implies when not to use the tool and points to an alternative (the override tool), but does not explicitly name it or cover other state transitions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds meaningful context: objects are in observe/warn mode (not yet adopted) and the tool must 'never auto-create a Scenario,' which is a valuable side-effect guarantee for a listing operation. However, it does not describe what the inventory returns, how results are structured, or any filtering/pagination behavior beyond the limit parameter.

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

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

The description is two sentences with no filler; the purpose is front-loaded and the safety caution earns its place. Minor deductions for unexplained domain jargon ('Scenario' capitalized without definition) and the slightly vague 'Map selected objects explicitly' directive, but overall the size and structure are appropriate for a simple list 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 simple tool with one optional parameter and no output schema, the description provides a solid start: scope, workflow placement, and a safety constraint. It is incomplete, though, because it never explains what the agent will receive back, what 'observe/warn mode' means, or how the limit parameter affects the result — and with no annotations, nothing else fills those gaps.

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

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

Schema description coverage is 0% and the description adds nothing about the sole parameter 'limit.' The schema's numeric bounds (maximum 200, exclusiveMinimum 0) convey range but not meaning, and the description does not compensate by explaining that limit caps the number of returned untracked objects. For a low-coverage schema, the description was expected to carry the parameter semantics and did not.

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

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

The description uses a specific verb and resource — 'inventory untracked catalog objects' — and narrows the scope with 'discovered in observe/warn mode,' which distinguishes it from sibling tools like agent_spec_list (tracked specs), agent_spec_adopt, and agent_spec_untracked_resolve. The differentiation is inferable rather than explicit, and the workflow hint 'before adoption' reinforces which stage this tool belongs to, but it never names a sibling.

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 clear context for when the tool applies: untracked catalog objects found in observe/warn mode. It also provides workflow guidance — map selected objects explicitly before adoption — and an explicit prohibition ('never auto-create a Scenario'). It does not, however, name the alternative tool to use for mapping/adoption, so the routing is implied 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?

No annotations are provided, so the description must disclose behavioral traits. It mentions 'close' (implying mutation) and a prerequisite for adoption, but it does not describe side effects (e.g., whether the item is removed, updated, or kept), reversibility, or any impact on related data. The tool's behavior beyond setting a state remains opaque, which is a significant gap for a mutation tool without 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?

The description is two sentences with no filler. The primary action is front-loaded, and the extra condition about adoption is presented succinctly. Every sentence contributes meaning, making it appropriately concise and well-structured.

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

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

The description is incomplete for an agent to safely invoke the tool. It lacks details on what happens after closing (no output schema), prerequisites for the 'ignored' state, how to obtain the Scenario id, and what object_id refers to. Given the tool's complexity and lack of annotations/output schema, the description leaves too many unanswered questions.

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 description does not explicitly map parameters. It hints that adoption requires a 'Scenario id' (likely spec_id), but does not confirm which parameter that is. object_id is not explained, and state is only described via the enum. With 0% schema coverage, the description should compensate by clarifying parameter roles, but it only provides a vague prerequisite hint, leaving most parameters ambiguous.

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 clearly states the action: explicitly close an untracked inventory item, with two possible outcomes (ignored or adopted). It distinguishes from sibling tools like yaaif_agent_spec_untracked_list (listing) and yaaif_agent_spec_adopt (adopting) by framing it as the closure step for untracked items. It is specific enough for an agent to grasp the core function.

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 usage condition: adoption requires the Scenario id after mapped bindings are reviewed. This hints at when to use the 'adopted' state, but it does not explicitly explain when to use this tool versus alternatives like yaaif_agent_spec_untracked_list or yaaif_agent_spec_adopt. The workflow context (e.g., first list untracked items, then resolve them) is implied but not 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?

With no annotations, the description carries the behavioral burden. It discloses the optimistic concurrency requirement ('using the version returned from its last read') and the replace_all restriction, which are important behavioral traits. However, it does not say whether omitted fields are left unchanged or cleared, what permissions are required, or what side effects occur beyond the update—gaps that matter for a mutation tool.

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

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

The description is two sentences with no wasted words. It front-loads the primary purpose and then immediately gives the most critical constraint and routing hint. Every clause adds value.

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 9 parameters, no annotations, and no output schema, yet the description covers only the concurrency check and the replace_all rule. It leaves ambiguous whether updates are partial or full replacement, how segments/requirements/slots arrays interact with existing data, and what the response contains. An agent would likely need to ask follow-up questions before first safe use.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It explains expected_version ('version returned from its last read') and replace_all ('replacement is only allowed with replace_all=true'), but it does not clarify the semantics of name, description, status, segments, slots, or requirements beyond their property names. With 9 parameters and zero schema descriptions, this is insufficient.

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 begins with a clear verb-resource pair: 'Update Scenario identity or segments'. It distinguishes from the many sibling update tools by noting that requirement/slot replacement should be done with replace_all=true or via granular tools, so an agent can tell this apart from yaaif_agent_spec_update_segment or yaaif_agent_spec_upsert_slots. It does not enumerate all updatable fields (e.g., status, description), but the core purpose 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?

The description explicitly states a key usage condition: 'Requirement and slot replacement is only allowed with replace_all=true; prefer granular tools.' This tells an agent when to use this tool versus the granular sibling toolsardt. It also implies when to use it: when updating the scenario's identity or segments and when doing wholesale replacement with replace_all=true.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Update', implying mutation, but does not mention optimistic concurrency via expected_version, validation rules, side effects, or what happens on version conflict. It also does not state whether partial updates are allowed or if all segment fields must be supplied. This is a significant gap for a mutation tool.

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

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

The description is a single sentence, concise and front-loaded with the core action. It avoids fluff and is easy to parse. While it could benefit from a second sentence on versioning or parameters, it is not verbose. The conciseness is appropriate given the minimal scope, though more detail would improve it without sacrificing brevity.

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

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

Given the complexity (8 parameters, 3 required, no output schema, no annotations), the description is severely incomplete. It does not explain what a segment is, enumerate valid segment keys beyond examples, clarify the role of expected_version, or describe the return value. An agent cannot safely call this tool based on the description alone; it would need to infer behavior from the schema or external knowledge.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. However, it only lists example segment keys and does not describe spec_id, expected_version, segment_key, title, status, body_md, payload, or sort_order. The description adds no value over the bare schema parameter names, which are ambiguous without explanations. Required parameters like expected_version are not mentioned at all.

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 clearly states the tool updates a single Scenario segment, listing example segment keys (overview, architecture, workflow_design, benefits). This is specific and distinguishes it from sibling tools like yaaif_agent_spec_update, which presumably updates the entire spec. The verb 'Update' and resource 'Scenario segment' are 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?

No guidance is provided on when to use this tool versus alternatives. Siblings include yaaif_agent_spec_update, yaaif_agent_spec_upsert_slots, and others, but the description does not mention when to choose this segment-specific update over a whole-spec update or other operations. No exclusions or context for selection 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the operation preserves other requirements and slots, which is useful, but it does not explain side effects, expected_version semantics, error conditions, or what happens on conflict. For a mutation tool, this is insufficient transparency.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core action and a key guarantee. However, it is under-specified rather than concise in a helpful way; the brevity sacrifices necessary detail. Still, the structure is clean and easy to parse.

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

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

Given the tool's complexity (nested requirement object, three required parameters, no output schema) and the absence of annotations, the description is grossly incomplete. It fails to explain versioning, the meaning of expected_version, the structure of acceptance criteria, or any failure modes. An agent would lack critical information needed to call this tool correctly.

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

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

Schema description coverage is 0%, so the description must compensate by explaining parameters. It does not mention spec_id, expected_version, or the requirement object's fields beyond what the schema already defines. The description adds no semantic meaning to any parameter, leaving agents to guess at the role of expected_version and the structure of requirement.

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 clear verb (create/update), resource (one typed requirement with acceptance criteria), and adds a specific detail (preserves every other requirement and slot). It distinguishes itself from sibling tools like upsert_slots or delete_requirement by its scope, but does not explicitly name alternatives. The purpose is unambiguous, though it could be sharper about when to choose this over similar 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?

There is no guidance on when to use this tool versus alternatives. The description does not mention conditions, prerequisites, or contrasts with sibling tools such as yaaif_agent_spec_upsert_slots or yaaif_agent_spec_delete_requirement. It only states the action, leaving the agent to infer usage context.

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

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

With no annotations, the description bears full responsibility for behavioral disclosure. It does mention the non-destructive aspect (without replacing the slot list), but fails to disclose optimistic concurrency behavior (expected_version), how requirement links are handled (replace vs. merge), or error conditions. Partial transparency only.

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

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

The description is a single sentence that front-loads the action and the key behavioral caveat. No unnecessary words 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?

The tool has a nested slot object with multiple fields, no output schema, and no annotations. The description leaves critical context unaddressed: what expected_version means, what constitutes a valid slot_key or kind, how requirement_keys are used, and the precise semantics of upsert. An agent would struggle to call this correctly based solely on the description.

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

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

Schema description coverage is 0%, so the description must compensate, but it does not explain any parameter meaning. The required parameters spec_id, expected_version, and slot are not mentioned, and nested fields like requirement_keys and kind remain unexplained.

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?

Description clearly states a specific verb (Create or update), resource (one architecture slot and its requirement links), and a key behavioral distinction (without replacing the slot list). This effectively differentiates it from upsert_slots (plural) and other slot-related 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?

The description implies a single-slot scope via 'one' and distinguishes from list replacement, but it does not explicitly state when to choose this tool over alternatives like yaaif_agent_spec_upsert_slots or yaaif_agent_spec_update. No conditions, exclusions, or alternatives are named.

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

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

With no annotations, the description carries the behavioral disclosure burden. It does disclose the key trait: this is an explicit replacement operation, not a normal incremental edit. However, it does not clarify whether slots omitted from the input are deleted, whether the operation is atomic, or how expected_version gates the replacement. The word 'every' is informative but somewhat ambiguous.

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 with zero waste. The actionable replacement behavior is front-loaded, and the alternative-tool guidance is a useful second sentence. Every word earns its place.

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

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

This is a destructive bulk operation with three required parameters, nested slot objects, no annotations, no output schema, and no parameter descriptions. The description is sufficient for tool selection but not for safe invocation: an agent would not know the full replacement semantics, how expected_version works, or the required shape of each slot entry.

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

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

Schema description coverage is 0%, and the description provides no additional meaning for spec_id, expected_version, or slots. It repeats the concept of 'architecture slot' but does not explain how to populate the nested slot items, what kinds are valid, or the role of expected_version. This is a significant gap for a tool with undocumented 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?

The description states a specific action: 'Explicitly replace every architecture slot.' It clearly identifies the resource (architecture slots) and the bulk-replacement nature, and it distinguishes this tool from the singular yaaif_agent_spec_upsert_slot sibling. An agent can understand what this tool is for 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?

The description explicitly names the alternative tool and the condition under which to prefer it: 'Prefer yaaif_agent_spec_upsert_slot for normal edits.' This gives the agent an actionable routing rule and implies that this tool is for explicit, bulk replacement rather than routine edits.

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