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

With no annotations, the description carries the full behavioral burden. It discloses that content is validated and enumerates acceptable role and cognition values, which are behavioral constraints not present in the schema. However, it does not explain what happens on validation failure, whether the operation is reversible, or any side effects, so it only partially discloses behavior.

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

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

The description is extremely brief and front-loads the action. Each clause adds information: the verb, the role domain, and the cognition-to-validation relationship. It avoids fluff but is so terse that some information is cryptic; still, it demonstrates discipline and earns a high score for conciseness.

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 complex debate context and 9 parameters, the description is notably incomplete. It does not define what qualifies as a valid 'turn', explain the Wind/Wall/Door roles or PATHOS/ETHOS/LOGOS cognition types, or connect this tool to the surrounding debate lifecycle. An output schema exists, but the description alone is not enough for an agent to use it correctly without external domain 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 is the only source of parameter meaning beyond the schema. It adds value for 'role' and 'cognition' by listing allowed values and implies 'content' is validated, but it leaves thread_id, agent_role, and the token_* parameters completely unexplained. With 9 parameters, this is insufficient compensation for the coverage 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 states the core action 'Record turn' with a clear verb and resource. It also lists allowed role and cognition values, which adds specificity and helps distinguish from sibling tools like tombstone_turn. However, it does not explicitly contrast with any sibling, so it stops short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives such as pick_next_speaker or human_interject. It is a standalone imperative without context about the debate workflow or conditions for recording a turn, leaving the agent to infer usage from the name and 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 provided, so the description carries the behavioral burden. It discloses side effects: closing the room and optionally creating an OCTAVE file in .hestai/state/context/decisions/ when export_decision is true. However, it does not state whether finalization is reversible, whether it requires special permissions, or what happens to the thread after closing.

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 relatively compact and front-loaded with 'Finalize debate,' but the arrow notation and 'Door's' phrasing are confusing. The Args section is clear for the three parameters it covers, but the overall structure is not polished and would benefit from clearer phrasing.

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 five-parameter tool with no annotations, the description is incomplete. It covers optional behaviors well but omits the required parameters' semantics, fails to differentiate from force_close_debate, and gives no usage context. The presence of an output schema helps, but it does not fill these 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%, so the description must compensate. It explains output_format, seal, and export_decision with useful detail, but it leaves the required thread_id and synthesis parameters essentially undocumented. The odd 'synthesis:Door's final resolution' line gives only a vague hint about synthesis.

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 'Finalize debate' and states the resource and action clearly: it finalizes a debate and closes the room. The phrase 'synthesis:Door's final resolution->closes room' is cryptic and slightly garbled, but the core purpose is still identifiable and distinct from siblings like force_close_debate.

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 call this tool versus force_close_debate or other debate lifecycle tools. It does not state prerequisites, alternatives, or conditions under which normal finalization should be preferred over force-closing.

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 is the only behavioral disclosure. It states the creation of a two-party mediated session, the question being recorded as the first turn, and a return dictionary. However, it does not disclose side effects like idempotency, thread lifecycle, or prerequisites—adequate but not exhaustive.

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

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

The description is front-loaded with the main purpose, but includes redundant phrasing—'Create advisory consultation session' followed by 'Creates a two-party mediated session.' The Args list is informative but adds length. It could be more concise without losing clarity.

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

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

The description covers the action, parameters, and return dictionary, making it largely complete for a creation tool. However, it omits usage context or exclusions, which would make it fully rounded. Given the output schema exists and parameters are well-described, it is adequate.

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. The 'Args:' section provides meaningful descriptions for each parameter, including defaults and examples (e.g., advisor_role: 'TMG', 'CE'). This fully addresses the schema gap and adds clear 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 clearly states 'Create advisory consultation session' and explains the two-party structure and the first turn being recorded. This is a specific verb+resource with distinct intent, and it distinguishes itself from debate-focused siblings like run_debate or init_debate.

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, nor does it mention conditions for choosing a different tool. It solely describes what the tool does, leaving usage context entirely to the agent's inference.

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

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

With no annotations, the description carries the burden. It explains that the tool creates a mediated session, that members respond and the chair manages order, and it lists the supported decision types. It also returns a status indicating the session is 'awaiting' input. This is good behavioral context, though it could mention potential side effects (e.g., asynchronous nature or state changes) but which are implied by 'session' and 'awaiting'.

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 well-structured with an opening summary, followed by a concise list of arguments and returns. It is appropriately sized for an 8-parameter tool. It front-loads the core action and decision types. A slight deduction for redundancy: the first two sentences overlap somewhat ('Assemble committee' vs 'Creates a mediated committee session').

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 params, 3 required, no annotations) and the presence of an output schema, the description covers the essentials: purpose, decision types, parameters, and return fields. It lacks explicit examples of usage or edge cases, but the output schema handles return structure. The description is sufficient for an agent to call the tool correctly, though it could be more explicit about when to choose this over debate tools.

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

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

Schema description coverage is 0%, so the description must compensate. It provides a clear list of all 8 parameters with brief explanations in the Args block, including defaults and examples for members. It adds meaning beyond the schema (e.g., what 'members' are, what 'decision_type' options are). It covers most parameters adequately, but some (like context) are only glossed over.

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 that the tool assembles a committee for group decision-making, with a specific verb ('assemble') and resource ('committee'). It also lists supported decision types, which helps distinguish it from siblings like init_debate that likely start a different deliberation format. However, it does not explicitly compare with siblings, so it misses the differentiation point for a 5.

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

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

The description implies usage when a committee-style decision is needed, and the mention of decision types (go_nogo, vote, review) gives context. However, it does not explicitly state when not to use this tool or mention alternative siblings like init_debate or consult. The absence of exclusions drops it from 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?

No annotations are present, so the description carries the full burden. It discloses error behavior (FileNotFoundError, ValueError) and the full return structure, which is helpful. However, it never explicitly states whether the operation is read-only or has side effects. 'Extract' implies no mutation, but the agent is left to infer it, which is a 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 well-structured with sections for Args, Returns, Raises. The introductory line is direct. The 'Cognitive Notary' context sentence is extra but brief and not harmful. Overall, it is efficient 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 one-parameter tool with an existing output schema, the description covers the argument semantics, the return categories, and error conditions. It does not mention authentication or rate limits, but these are expected to be covered elsewhere; the missing piece is an explicit read-only statement, which is already noted under behavioral transparency. Overall the description is functionally 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?

The input schema only defines thread_id as a string with no description (0% coverage). The description's Args section adds the meaning 'Thread identifier of closed debate', which is essential and compensates for the schema gap. It could be more detailed (e.g., where to find it), but for a single obvious parameter it's sufficient.

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 leads with a specific verb ('Extract') and a concrete resource ('DecisionRecord'), and qualifies the source as 'a closed debate'. This distinguishes it from siblings like search_decisions (search) and get_debate (get the debate itself). The purpose is unambiguous and not a tautology.

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 states the prerequisite that the debate must be closed, and documents that ValueError is raised for ACTIVE or PAUSED debates, so an agent knows when it is appropriate to call. However, it does not explicitly name alternative tools or say 'do not use when...' for specific scenarios beyond the state condition. Clear context, no 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?

No annotations are provided, so the description carries the full burden. It discloses that the tool is a safety override and that the reason is logged, but it does not explain side effects, irreversibility, or what 'any state' means. The behavior is vague and potentially destructive without adequate 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 extremely short, but it is not effectively concise—it is cryptic and under-specified. The 'I5:safety override' prefix and 'reason:logged→' notation are unclear and waste the reader's effort decoding them.

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 is a safety override with destructive implications, the description is inadequate. It does not explain what 'any state' means, what happens to the debate, whether it is reversible, or how it differs from close_debate. The output schema exists but the description still fails to provide essential context for a potentially destructive operation.

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 parameters. 'reason' and 'thread_id' are self-explanatory from their names, but the description adds no meaning about how they are used or why they are required. The 'reason:logged' hint is the only parameter-related context, and it is cryptic.

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 'I5:safety override. reason:logged→force closes any state.' is cryptic and does not clearly state what the tool does. It mentions 'force closes any state' but lacks a clear verb-resource relationship and does not distinguish it from sibling tools like close_debate. The 'I5:safety override' prefix is unexplained jargon.

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 this is a safety override for force-closing debates, but it does not explicitly state when to use it versus close_debate or other siblings. No exclusions or alternative conditions are provided, leaving the agent to guess 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?

With no annotations provided, the description carries the behavioral burden. It adds useful behavior details, such as include_transcript adding turn history and context_turns limiting depth, but it never explicitly states that this is a read-only operation or mentions permissions, errors, 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?

The description is extremely short, with no filler, and front-loads the core return shape first. The arrow-based shorthand is compact but slightly cryptic, which prevents a perfect score.

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

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

Despite having an output schema, the description is incomplete given four parameters, no annotations, and a large sibling set. It omits include_metadata semantics and provides no usage differentiation, leaving the agent to infer important 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. It adds meaning for context_turns and include_transcript, but it does not explain include_metadata or the thread_id relationship, though thread_id is fairly self-evident from the 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 communicates that the tool returns debate state and optionally a transcript, and the name get_debate identifies the resource. It is clear on the basic purpose, but it does not differentiate itself from siblings like search_decisions or extract_decision_record.

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 about when to use this tool versus alternatives such as search_decisions or resume_debate. The parameter notes describe effects, not selection criteria or when-not-to-use conditions.

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 full burden of behavioral disclosure. It explicitly states idempotency ('tracks synced turns to avoid duplicates'), the write behavior ('Posts new turns'), and the two API pathways (GraphQL vs REST). It does not mention authentication or rate limits, but the core behavioral risks are covered well.

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 compact and well-structured: purpose first, then behavior, then args, then an operational note. Every sentence adds value and the Args block is easy to scan. There is no filler or 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?

The description is complete for an agent to invoke the tool correctly: all four parameters are semantically explained, the idempotency behavior is disclosed, and the GitHub target ambiguity (discussion vs issue) is resolved. Since an output schema exists, return-value details are not required here.

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 no property descriptions (0% coverage), so the description must fully compensate. It does: thread_id is explained as the debate thread to sync, repo is given in owner/repo format, target_id distinguishes GitHub node ID from issue number, and target_type is mapped to 'discussion' (GraphQL) or 'issue' (REST). This is exactly the semantic content an agent needs.

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

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

The first sentence uses a specific verb ('Sync') with a clear resource ('debate turns') and destination ('GitHub Discussion/Issue comments'). The follow-up 'Posts new turns as formatted comments with cognition headers' removes any ambiguity about what the tool actually does. It is clearly distinguished from all sibling tools, which are debate-management operations rather than GitHub synchronization.

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

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

The description makes the context of use clear: this is the tool for mirroring debate turns into GitHub discussions or issues. It does not name alternatives, but no sibling tool performs GitHub syncing, so exclusion guidance is not necessary. The note about GITHUB_TOOLS_ENABLED=false adds a useful operational condition.

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 burden. It discloses that the tool fetches from GitHub, adds to debate context, and detects which role was replied to. It also mentions a feature flag that can disable the tool. However, it does not disclose side effects like whether the debate state is mutated, whether the comment is permanently stored, or any permission requirements.

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 compact and front-loaded with the main purpose. The Args block is useful and the note about the feature flag is relevant. It is slightly repetitive ('Inject... as context' vs 'Fetches... and adds to debate context') but overall 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?

The tool has 4 required parameters, no annotations, and an output schema. The description covers the core behavior and parameter meanings, but lacks details on return values, error conditions, and the exact distinction between discussion and issue IDs. Given the complexity of GitHub API interactions, more context would help an agent 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 the description must compensate. It provides brief explanations for all four parameters in the Args block, but these are terse and mostly restate the parameter names (e.g., 'thread_id: The debate thread to inject into'). It does not explain formats like 'DC_...' beyond a parenthetical, nor how target_id differs between discussions and issues in practical terms.

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 ('Inject') and resource ('human GitHub comment into active debate as context'), and clarifies it fetches a comment and adds it to debate context. It distinguishes itself from siblings like github_sync_debate by focusing on injecting a single human comment, though it doesn't explicitly name a sibling alternative.

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

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

The description implies when to use it: when a human comment needs to be injected into an active debate. It does not explicitly state when not to use it or name alternatives like github_sync_debate. The note about GITHUB_TOOLS_ENABLED=false provides a conditional usage constraint, but no explicit comparison to sibling 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 of behavioral disclosure. It adds a cryptic behavior hint ('strict_cognition->validate turns') but does not explain side effects, whether creation is idempotent, permission needs, or what 'validate turns' actually entails.

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 very short and has no filler, but the telegraphic fragments sacrifice clarity. 'mode:fixed|mediated' and 'strict_cognition->validate turns' are compressed to the point of being cryptic rather than helpful.

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

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

For a 7-parameter tool with no annotations and no schema descriptions, this description is far from complete. It omits required parameters, optional controls, and the tool's place in the debate workflow. The output schema exists but does not compensate for missing invocation guidance.

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 there are 7 parameters. The description adds limited semantics for mode ('fixed|mediated') and strict_cognition ('validate turns'), but does not mention thread_id, topic, max_turns, max_rounds, or octave_mode, leaving most parameters 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 says 'Create room,' which gives a verb and object, but 'room' is vague and doesn't explicitly say 'debate room' or distinguish this from sibling tools like convene or run_debate. The tool name init_debate provides some disambiguation, but the description itself lacks specificity.

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 init_debate versus alternatives such as add_turn, run_debate, or convene. It does not state prerequisites, ordering, or scenarios where another tool would be more 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 provided, the description carries the full burden of behavioral disclosure. It indicates a state change ('sets next expected speaker') but does not mention side effects, permissions, reversibility, failure modes in non-mediated mode, or any impact on debate state. 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, tightly packed line. It front-loads the critical mode constraint ('Mediated mode only') and then gives the role mapping. There is no filler or redundancy; every word contributes.

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 low-complexity (2 required params, simple mutation) and an output schema exists, so return values are covered. However, the description omits what 'thread_id' refers to and what 'next expected speaker' means in the broader debate flow. It is minimally adequate but leaves contextual gaps that an agent must infer.

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 adds meaning to the 'role' parameter by listing allowed values (Wind|Wall|Door), but it provides no additional semantics for 'thread_id', which is left to the parameter name. Partial compensation for a coverage 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 states a specific action ('sets next expected speaker') and resource with a clear mode constraint ('Mediated mode only'). It conveys the role mapping (Wind|Wall|Door), which helps distinguish this from generic debate tools, though it doesn't explicitly name sibling alternatives.

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 'Mediated mode only' implies when the tool is appropriate, but it does not explain when to prefer this over siblings like add_turn or run_debate, nor does it give exclusion criteria. The usage context is implied rather than explicitly contrasted.

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 of behavioral disclosure. It explicitly reveals that the tool creates a PR, making the mutating nature clear, and includes a useful configuration note about GITHUB_TOOLS_ENABLED=false. However, it does not mention permissions, reversibility, or failure behavior, which would be valuable for a write 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 description is well-structured with clear sections: purpose, Requires, Args, Returns, and Note. Every section contributes necessary information. It is slightly longer than necessary because it restates all parameters, but since the schema lacks descriptions, this repetition is justified.

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

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

The description covers the tool's purpose, precondition, all parameter semantics, return values, and an environment-based disable note. It is reasonably complete for invoking the tool correctly. It lacks alternative-tool guidance and error-condition context, but those are secondary given the output schema exists and the description already covers the critical 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?

Schema description coverage is 0%, so the description must compensate. It does: each parameter gets a meaningful one-line explanation, such as 'repo: Repository in owner/repo format' and 'adr_number: Explicit ADR number (required to prevent collisions).' The parameter descriptions add real semantic value 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 opening sentence states a specific action: 'Generate ADR from Door synthesis and create PR.' This clearly identifies the tool's resource and outcome. However, it does not explicitly differentiate itself from siblings like extract_decision_record, which could plausibly overlap in purpose.

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 clear precondition: 'Requires: Debate must be closed with synthesis.' This gives the agent a concrete gate for when to call the tool. It does not mention alternatives or exclusions, 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?

No annotations are provided, so the description carries the full behavioral burden. It discloses the process (thread generation, debate run, decision extraction), the return payload, and the possible RuntimeError/ValueError outcomes. This is transparent enough, though it could mention persistence/side-effect details such as thread creation more explicitly.

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 well-structured with a purpose statement, numbered process, Args section, Returns section, and Raises section. It is detailed yet every sentence earns its place, with the primary purpose 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-step tool with no annotations and an output schema, the description covers the full call flow: inputs, processing, return shape, and error conditions. Nothing an agent needs to call it correctly or understand its result is missing.

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

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

Schema description coverage is 0%, but the description compensates fully by explaining all three parameters: topic as the question, tier as a configuration name with a default, and thread_id as optional with auto-generation when None. This adds real meaning 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 states a specific verb ('Resolve a question') and resource ('structured debate... decision record'), and explicitly frames itself as a Layer 3 combination of run_debate + extract_decision_record. This clearly distinguishes it from sibling tools and leaves no ambiguity about what it does.

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 says agents call this 'for quick, verified decisions' and explains that it wraps two lower-level tools into a single operation. This gives clear context for when to use it, though it does not explicitly state when not to use it or name alternative tools for raw debate access.

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 disclosure burden. It does add useful context about resuming from Phase 4 and the failure-triggered pause scenario, plus a return summary. However, it does not disclose side effects, idempotency, whether state is mutated, or what happens if the debate is not actually paused.

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 compact, well-organized with Args/Returns sections, and front-loads the core purpose in the first sentence. Every line adds useful information without filler or redundancy.

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

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

For a tool with moderate complexity, the description covers what it does, when it applies, key parameters, and return contents. The main gap is the absence of explicit preconditions or failure behavior—such as what occurs if the thread is not a paused debate—but overall it is sufficiently complete for selection and initial 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 description coverage is 0%, so the description must compensate. It lists each parameter and clarifies defaults and override behavior (e.g., 'None = use tier default'). However, it does not define what the tiers mean or how compression_tier and primer_tier affect behavior, leaving semantic ambiguity beyond the schema.

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

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

The description opens with a specific verb ('Resume') and a precise resource ('a PAUSED debate') and adds the phase detail ('from where it left off (Phase 4)'). This clearly distinguishes it from siblings like init_debate, run_debate, and get_debate.

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 when to use the tool: resuming debates paused due to failures during auto-orchestration, such as provider timeouts or errors. It does not explicitly mention when not to use it or name alternative tools, but the context is clear enough for an agent to identify the intended scenario.

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

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

With no annotations, the description carries the behavioral burden, and it does well: it reveals that three agents run roles, that context files are injected into prompts, that raci_config is required for raci mode, and that the return value includes thread_id, status, and synthesis. It does not explicitly disclose side effects like thread persistence or whether a new thread is created, but the auto-generated thread_id strongly implies 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?

Despite covering many parameters and modes, the description remains well-structured and efficient. The one-sentence summary is front-loaded, followed by scannable bullets for agents, arguments, and return values. No sentence is redundant or 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?

The description is complete enough to correctly invoke the tool: it covers all required parameters, mode-specific requirements, defaults, overrides, and return fields. Minor gaps remain, such as defining what values 'tier' accepts and explicit side-effect behavior, but the output schema and detailed argument docs make these non-blocking.

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 fully compensate, and it does. Each parameter is explained beyond the schema: context_files are 'absolute file paths' injected into prompts, mode explains all three options, and raci_config provides a detailed role dictionary with required and optional fields including max counts.

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

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

States a specific verb and resource: 'Auto-orchestrate a Wind/Wall/Door debate (ADR-0002).' It goes on to name the three agents and their roles, making the tool's function unambiguous and distinct from manual debate helpers like init_debate or add_turn.

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?

Clear context is provided: this runs a 'complete automated debate' with three agents, implying it is the orchestration entry point rather than a step-by-step tool. It also explains when to use each mode ('standard', 'speed', 'raci'), but does not explicitly name alternatives or state when not to use this 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 burden of behavioral disclosure. It reveals that the search is ranked, uses BM25 with specific field weights, and returns a structured dictionary. It also explains the min_score threshold. However, it does not explicitly state whether the operation is read-only or mention any side effects, permissions, or rate limits. For a search tool, the provided detail is substantial but not exhaustive, meriting a 4.

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 well-structured and front-loaded with the core purpose. It then provides field weights, arguments, and return format. While it is somewhat lengthy, every sentence adds useful information for an agent (especially the field weights, which inform query tuning). It could be slightly tightened, but the structure aids comprehension.

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 complete for an agent to call this tool correctly. It explains all parameters, the return dictionary structure, and the scoring mechanism. Given that this is a read-only search operation and no output schema is provided in the context, the description fully covers what an agent needs to know. No critical gaps remain.

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 description coverage is 0%, so the description must compensate. It does so comprehensively: each parameter is explicitly explained in the 'Args' section, including defaults and value ranges (e.g., min_score 0-1). This adds significant meaning beyond the raw schema, which only lists types and defaults.

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 function: 'Search for past decisions matching a query.' It specifies the resource (decisions directory), the method (field-weighted BM25), and the output (ranked results with relevance scores). This distinguishes it from sibling tools like get_debate or consult, which serve different purposes.

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

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

The description explains what the tool does but does not explicitly state when to use it over alternatives or provide exclusions. It implies usage for searching decisions, but no guidance on when not to use it (e.g., if you already have a thread_id, use get_debate). Sibling tools are not referenced. This leaves the agent to infer appropriate usage from the tool's purpose alone.

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

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

With no annotations provided, the description carries the full burden of disclosing behavior. It does disclose one useful fact: the hash chain is preserved when redacting. However, it does not state whether the operation is destructive/irreversible, whether content is actually removed or replaced, or any permission or side-effect information. The tombstone implication is left implicit.

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 extremely short, but it sacrifices clarity. The 'I4:' prefix is unexplained jargon, the arrow notation is unconventional, and the two sentences are fragmented. While brevity is a virtue, this reads as a terse internal note rather than a structured user-facing description.

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 that the tool has an output schema but no parameter descriptions and no annotations, the description is grossly inadequate for correct invocation. It does not explain what a tombstoned turn means, how it affects the debate state, why a reason is required, or what the return value represents. An agent cannot confidently call 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%, so the description must compensate for all three parameters (thread_id, turn_index, reason). It only clarifies that turn_index is 0-based. No meaning is added for thread_id or reason, and the relationship between the parameters and the redaction behavior is 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 says 'redact content→hash chain preserved' which implies the tool redacts some content while maintaining a hash chain. However, it never explicitly ties the action to a 'turn' resource, uses cryptic 'I4:' prefix, and does not clearly distinguish it from siblings like add_turn or close_debate. The purpose is inferred but not clearly stated.

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 compared to other debate-management tools like close_debate or human_interject. No exclusions, no context, no mention of prerequisites. An agent would have to guess when tombstone_turn is the right choice.

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