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

With no annotations provided, the description fully discloses behavior: guards (StateError for out-of-project, terminal status requiring force, live owner conflict), force parameter effects, and warning emission. This is comprehensive 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 well-structured with clear sections (Use when, Guards, Input, Output, Example). It is reasonably concise, though some redundancy exists (e.g., repeating force description in Guards and Input).

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

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

No output schema exists, so the description correctly lists output fields and provides an example. Combined with the comprehensive behavioral details, it leaves no gaps for the agent to 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 coverage is 0%, but the description compensates by explaining run_path as an absolute path and force as an override for guards. It adds meaning beyond schema defaults (false/empty string) but could provide examples of valid run_path 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 explicitly states 'Transfer an existing run's pin to the caller's session,' which is a specific verb-resource combination. It clearly distinguishes this tool from siblings focused on other operations (e.g., trw_deliver, trw_init).

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 explicit 'Use when' scenarios: resuming a run from another session or reclaiming an abandoned run. It also details guards and conditions, guiding the agent on when to use this tool versus 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 must carry the burden. It mentions 'privacy-safe' and 'schema-valid', implying data sanitization and standardized output. However, it does not disclose permissions, side effects, or what happens if run_path is null. More details on behavioral traits would be beneficial.

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 long, with the purpose front-loaded and usage guidelines in the second sentence. Every word adds value with no wasted text.

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 no output schema, the description could explain the return structure (e.g., 'returns a JSON object conforming to AgentWorkEvidence v1'). It also omits clarification on default behavior when run_path is not provided. For a tool with three optional parameters, these gaps reduce completeness.

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

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

The input schema provides 100% coverage with descriptions for all three parameters. The description adds no extra semantic meaning beyond what the schema already offers, so a baseline score of 3 is appropriate.

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

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

The description clearly states the verb 'Export' and the resource 'privacy-safe AgentWorkEvidence' for a TRW run. It distinguishes from siblings by noting it avoids scraping run internals, and among siblings like trw_validate_agent_work_evidence, the purpose is unique.

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 lists who should use it (judge, eval harness, reviewer, knowledge-graph importer) and what alternative to avoid (scraping run internals). While it does not enumerate sibling tools as alternatives, the provided context is sufficient for most use cases.

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 full burden. It discloses it never raises, details failure paths (distill_status/action), mentions sources (sidecar, recalls), and tier-gating. It does not explicitly state side effects but implies read-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?

Description is concise (6 lines) with clear sections: purpose, usage, sources, error behavior. Front-loaded, no fluff, but could be slightly more 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?

Output schema exists, reducing need for return value detail. Description covers purpose, usage, error handling, and sources. Missing: optional parameter descriptions and operational details like rate limits or permissions.

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 has 0% description coverage. Description explains the main parameter file_path but ignores cache_dir and repo_root, leaving those semantically unenriched.

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 the tool returns cold-start codebase intelligence for a file_path, with an explicit use case (before editing). However, it does not explicitly differentiate from its sibling trw_before_edit_hint_batch, though the name implies singular vs batch.

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?

Description explains when to use (before editing a file needing risk context and prior learnings) but does not provide exclusions or compare with alternatives like trw_before_edit_hint_batch.

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 description carries full burden. It discloses return type (model_dump()), promises never raises, and mentions tier-gating. Does not mention mutations, but tool name suggests read-only operation. Minor gap: no mention of whether it relies on sidecar state or any prerequisites.

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

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

Three sentences, each serving a distinct purpose: purpose, usage context, and constraints. No superfluous text, front-loaded with the core verb and resource.

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?

Output schema exists, so return format is covered. However, parameter semantics are missing, and the description assumes the agent knows about 'current SHA' and 'persisted trw-distill sidecar'. The description is adequate for an agent with context, but incomplete for a new one.

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 (cache_dir, repo_root). The agent has no guidance on what values to provide, leaving the agent to guess or ignore the parameters. This significantly hinders correct invocation.

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 what the tool does: 'Return c735+c743 BeforeYouEditBatch for the current SHA.' It specifies the resource (batch hints) and distinguishes from the sibling tool trw_before_edit_hint by noting it's for multi-file edits and is paid-tier only.

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

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

Explicit usage guidance: 'Use when an agent is planning a multi-file edit and needs batched before-edit hints.' Also provides alternative for free-tier users: 'see trw_before_edit_hint for the free-tier learnings counterpart.'

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 reveals critical behaviors: does not execute subprocesses, conditionally fails tests based on min_coverage, and lists output fields. It does not mention authorization or side effects, but for a recording tool, it is sufficiently 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 well-structured with clear sections (Use when, Input, Output) and front-loaded with the main purpose. While it is fairly long due to 10 parameters, every sentence adds value; no wasted words. Slightly verbose but efficient for the 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 10 parameters, no annotations, and no output schema, the description is exceptionally complete. It covers all parameter meanings, usage context, behavioral nuances, and output fields. An agent can confidently invoke the tool without additional documentation.

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%, but the tool description compensates excellently. Every parameter is explained with its purpose, constraints, and behavioral effects (e.g., min_coverage falling tests_passed, mypy_clean as legacy alias). This adds significant value beyond the plain 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 records build/test results for ceremony tracking and delivery gates. It specifies the verb (record) and resource (build/test results), and the multiple use cases (after validation, for delivery gates, Q-learning feedback) differentiate it from 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 provides explicit when-to-use scenarios and a key when-not instruction: 'This tool does NOT execute subprocesses — run validation commands first, then call this with the results.' It lacks explicit alternative tool names, but the context is clear enough for most agents.

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 explains the output format and the survival property, but does not disclose side effects, permissions, or safety characteristics. It provides sufficient transparency for a non-destructive logging 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 concise, with distinct sections for purpose, usage, input, and output. Every sentence adds value and there is no fluff.

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 and output schema, the description covers purpose, usage, parameter meanings, and output format. It is fairly complete for the tool's simplicity, though it lacks details on default behavior when run_path is absent.

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

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

The description adds meaning beyond the schema by clarifying that message is required (contradicting schema) and that shard_id and wave_id are for annotation. However, it misstates required status, reducing reliability. Schema coverage is 0% so compensation is needed, but the contradiction harms clarity.

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 appends a progress snapshot for survival across context compaction. The verb 'append' and resource 'progress snapshot' are specific, and the purpose is distinct from siblings like trw_pre_compact_checkpoint or trw_heartbeat.

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 lists when to use: after a milestone or before compaction/interruption, and after each meaningful work batch. This provides clear guidance, though it does not mention when not to use or identify alternatives among 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?

With no annotations, the description carries full burden. It discloses the deprecation warning on every invocation and states output is identical to trw_instructions_sync. Though it doesn't detail the sync operation itself, the alias behavior and output equivalence are sufficiently transparent for a deprecated 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?

Very concise and front-loaded: the first sentence declares deprecation and alias. Every sentence adds value, with no wasted words.

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 deprecated alias, the description adequately covers purpose and output equivalence. However, it lacks parameter documentation and no output schema is provided, which is a gap for correct invocation. Completes the immediate context but leaves invocation details underspecified.

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 does not explain the parameters (scope, client, target_dir) at all. It only mentions output fields. This leaves the agent with no semantic guidance for parameter values 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 clearly states it is a deprecated alias for trw_instructions_sync, with a specific verb ('maintaining backward compatibility') and resource ('alias'). It distinguishes itself from siblings by noting deprecation and redirecting to the preferred 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?

Explicitly specifies when to use (backward compatibility) and when not to ('prefer trw_instructions_sync in new code'). Also mentions deprecation warning and future removal, guiding the agent's 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 bears full burden. It discloses tier-gating, top_n behavior (default 20, 0 returns all), return format (model_dump enriched by tier), and states 'NEVER raises'. It lacks details on prerequisites like sidecar existence or authentication, but provides substantial behavioral information.

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 wasted words. It front-loads the purpose, then usage, then details. Every sentence 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?

For a tool with 3 parameters and an output schema (so return values are documented), the description covers purpose, usage, key parameter, and behavioral note. The only gap is the two undocumented parameters (cache_dir, repo_root). Overall very functional.

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 description must compensate. It explains top_n thoroughly (0 returns all, default 20) but does not explain cache_dir or repo_root at all. Only one of three parameters is given meaning 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 clearly states it returns a 'c737/c739 ranked composite-risk report for the current SHA', providing a specific verb and resource. It distinguishes itself from sibling tools like trw_entity_risk_map by referencing specific report codes and the use case for review prioritization.

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 'Use when a reviewer needs file-level structural risk ordering...before prioritizing review effort', giving clear context. It does not explicitly state when not to use or mention alternative tools, but the use case is specific 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 bears full responsibility for behavioral disclosure. It mentions 'update' but does not clarify whether the operation is destructive, idempotent, or what side effects occur (e.g., disk writes). Missing details about safety, permissions, or concurrency risks 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 sentences with no wasted words. The first sentence names the action and object (the manifest), and the second provides concrete usage guidance. Perfectly 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?

The description explains why to use it and when, but given no output schema and lack of annotations, it omits behavioral context like idempotency, prerequisites (e.g., repo_root validity), and how paths affect the index. Schema descriptions help, but the overall completeness is average for a tool with three 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 100%, setting baseline at 3. The description adds no extra meaning beyond the schema; it only names the tool's purpose. The parameter descriptions in the schema already explain force, paths, and repo_root adequately.

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 explicitly states it updates a 'local SHA-256 code-index manifest' and specifies its use case: 'before code search or symbol analysis without returning file bodies.' This clearly distinguishes it from siblings like trw_code_search and trw_code_symbol, which operate on the index instead of updating it.

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 tells when to use the tool ('before code search or symbol analysis'). It implies an ordering dependency but does not explicitly state when not to use it or mention alternatives. Given sibling names, the context is sufficient but could be more precise.

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. The description discloses that it searches indexed chunks and returns ranked context, and implies a prerequisite. However, it lacks details on side effects, auth needs, or whether it mutates state. The description adds some value but not enough for full 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 succinct sentences with no wasted words. The key information 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?

Despite clear purpose and usage, the description does not explain what 'ranked code context' means nor how parameters like 'mode', 'path', and 'top_k' affect results. With no output schema, the description is incomplete for a search tool with tuning options.

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 parameter descriptions). The description adds no meaning to the five parameters. For a tool with multiple parameters, 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 'Search' and the resource 'local indexed code chunks', distinguishing this tool from siblings like 'trw_code_index_update' which indexes code. The purpose is specific and actionable.

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

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

Explicitly states when to use: after 'trw_code_index_update' has run, and when needing ranked code context without reading full files. This provides clear context and 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 provided, so description must carry full burden. Discloses indexing behavior and ranking, but lacks details on return format, failure modes, or whether results are limited to exact matches.

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

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

Two sentences, front-loaded with purpose, no redundant information. 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?

With 4 parameters, no output schema, and no annotations, the description fails to cover parameter meaning or return value structure. Incomplete for effective 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 coverage is 0%, yet description provides no explanation of parameters like 'path' or 'top_k'. The required 'repo_root' and 'symbol' are not clarified.

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?

Clear verb 'find' and specific resource 'local indexed symbols' with 'exact matches ranked first'. Distinguishes from siblings like trw_code_search and trw_code_index_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?

Explicit when to use: 'when an agent needs symbol locations from the local code index'. Also states what it avoids: 'without scanning or returning full file bodies.' Could be more explicit about 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 provided, so description carries full burden. It discloses key traits: 'NEVER raises' (no exceptions), 'Tier-gated' (auth restriction), and explains sidecar SHA derivation. Could mention side effects (none) but overall strong transparency for a read 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?

Description is six sentences, each purposeful. Front-loaded with purpose, then usage, then behavioral details. No repetition or fluff. Efficiently uses whitespace.

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 3 optional params, output schema exists, and no annotations, the description covers purpose, usage, and behavioral traits. It notes that the tool searches repo-default location if sidecar path not given. Minor gaps: no mention of return format or idempotency, but output schema handles return values.

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 has 0% parameter coverage, so description must compensate. It mentions sidecar_path and sidecar_dir options but does not explain repo_root. Also lacks details on parameter types, defaults, or constraints. Only partial guidance on how parameters affect behavior.

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 it returns the latest c745 CrossRepoOrderingAggregate. The verb 'Return' and specific resource name make the action unambiguous, distinguishing it from sibling tools like trw_ordering_compare by focusing on cross-repo aggregate sidecar.

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

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

Explicitly states when to use: 'when comparing structural-risk ordering consistency across multiple repositories from a persisted aggregate sidecar.' Also clarifies that sidecar SHA is derived from sorted repo names, not git HEAD. However, no explicit when-not-to-use or alternatives listed.

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?

Since no annotations are provided, the description carries the full burden. It explains synchronous execution of reflect and checkpoint, then asynchronous background work with concurrency safety (overlapping batches skipped). However, it doesn't detail error handling or what happens on failures beyond the output errors field. Still, it covers key behavioral traits 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?

Well-structured with sections: purpose, use cases, pre-check, behavior, parameters, output, example, see also. Each sentence adds value; no fluff. The length is appropriate 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 no output schema, the description provides a detailed output structure with field names and types, plus an example. It covers the essential aspects but could be more explicit about some fields like 'deferred' and 'critical_steps_completed'. Overall, it gives enough context for an agent to understand what 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?

Despite 0% schema description coverage, the description explains each parameter clearly: run_path (auto-detected), skip_reflect, skip_index_sync, allow_unverified (explicit override), unverified_reason (required rationale). This adds significant meaning beyond the bare schema, though it doesn't elaborate on data types beyond what the schema provides.

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

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

The description clearly states the tool's purpose: 'Persist learnings and progress so future sessions inherit this session's work.' It uses a specific verb (persist) and resource (learnings and progress). It also distinguishes from siblings by listing see-also tools and explaining what this tool does differently (e.g., background housekeeping vs trw_checkpoint).

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

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

Explicitly provides 'Use when' scenarios: session about to end, milestone reached. Includes a precondition check ('did you record at least one discovery with trw_learn?') and advice to add a learning if not. This gives clear decision support for when to call the 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?

No annotations are provided, so the description carries the full burden. It discloses one important behavioral trait: 'NEVER raises for sidecar failures.' However, it does not mention whether the tool is read-only, requires specific permissions, or has side effects. The disclosure is incomplete for a 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 concise with four sentences, each serving a purpose: stating the action, providing usage context, explaining a parameter behavior, and giving a safety guarantee. Front-loaded with the primary 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?

Although an output schema exists, the description does not fully explain all parameters (only top_n is partially covered). It also does not clarify what 'structural risk rows' entail. For a tool with 4 parameters and no schema descriptions, the description is incomplete.

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

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

Schema coverage is 0%, so the description must add meaning. It only explains the top_n parameter (top_n=0 returns all matching rows). The other three parameters (cache_dir, repo_root, changed_only) are not described. This partially compensates but leaves significant gaps.

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 'Return' and the resource 'entity-level structural risk rows for the current SHA'. It also provides a use case: when a reviewer needs symbol/function/class/endpoint blast-radius triage from a persisted sidecar. This distinguishes it from sibling tools like trw_codebase_risk_report.

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 specifies when to use the tool ('when a reviewer needs ... triage') and mentions it is tier-gated. It does not explicitly mention when not to use or provide alternatives, but the context is clear enough for an agent to understand 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?

No annotations are provided, so the description carries the full burden. It fully discloses the rate-limiting behavior, the short-circuit condition based on a 60-second window, the state persistence in pins.json, the output structure on success, and the error case for missing pin. This is a comprehensive behavioral 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 appropriately sized and front-loaded with a one-line summary. It uses clear section headers (Use when, Rate-limit, Input, Output) and bullet points for readability. Every sentence adds value without waste.

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 no output schema, the description lists the result fields (run_id, last_heartbeat_ts, etc.) and error case. Given the tool's simplicity (one optional parameter), the description is complete and provides sufficient context for an AI agent 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?

With schema description coverage at 0%, the description must compensate. It does so by explaining the only parameter 'message' as 'optional context string logged alongside the heartbeat event.' This adds meaning beyond the schema's default and type.

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 purpose: 'Refresh the caller's pin heartbeat and append a heartbeat event.' It uses specific verbs and resources, and given the sibling tools like trw_init, trw_checkpoint, and trw_probe, the description provides context that distinguishes it as a keep-alive mechanism for long-running campaigns.

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 provides usage scenarios: 'Use when: - A long-running campaign needs to keep its pin alive between work units. - You want to probe whether the current run is stale enough to checkpoint.' This gives clear guidance on when to use this tool versus 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 must disclose behavioral traits. It mentions creating, registering, bootstrapping state, metadata, events, and assets, but lacks details on side effects, failure modes, or required permissions. Adequate but 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 structured with a lead sentence and bullet points. It is reasonably concise, though some redundancy exists. The bullet list improves readability without excessive length.

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

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

Given the tool's complexity (13 params, no output schema, no annotations), the description is incomplete. It briefly mentions output fields but doesn't explain their semantics, error conditions, or preconditions. More detail is needed for an initialization tool.

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

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

The input schema has 13 parameters with 0% description coverage. The description lists some parameters (task_name, objective, config_overrides, etc.) but omits others like run_type, task_type, planning_mode, and doesn't explain their meanings or formats. This leaves significant gaps.

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 'Create a run directory and register it as the active run' with a clear verb and resource. It lists specific actions like bootstrapping state, run metadata, etc., distinguishing it from sibling tools like trw_adopt_run.

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 'Use when' bullet points provide clear context: starting a new task, sprint, investigation needing persistent state. While it doesn't explicitly state when not to use or name alternatives, the guidance is sufficient for typical use cases.

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, but the description explains what the tool does (renders guidance into instruction files) and what it does not do (promote learnings). It also mentions the output format. However, it does not clarify whether it overwrites or merges existing content, leaving some behavioral ambiguity.

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?

Well-structured: a summary sentence, bullet-pointed use cases, a behavioral paragraph, and output format. Every sentence is informative and there is no 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?

Given the tool's purpose (sync multiple instruction files) and 3 parameters fully documented, the description covers use cases, behavior, and output. It is complete enough for an agent to decide when and how to use it.

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

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

Schema coverage is 100%, so baseline is 3. The description adds value by contextualizing parameters (e.g., 'auto' client detection, scope for root vs sub), which goes beyond the schema's basic 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 the tool syncs TRW protocol and ceremony guidance into the client's instruction file. It uses a specific verb ('Sync') and resource, and distinguishes from sibling tools like trw_session_start by noting that learnings are not promoted.

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

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

Explicitly lists three 'Use when' scenarios: onboarding new project, after changing protocol template, and when switching IDE clients. Also states when not to use (for learning promotion) and directs to trw_session_start for that purpose.

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 clearly indicates this is a write operation (persist), describes the output status (saved/deduped/error), and mentions auto-detection of metadata. It could explicitly state idempotency or deduplication behavior, but it does cover the main behavioral aspects. Score 4 for good but not exhaustive 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 relatively long but well-organized into sections (purpose, use-when, only-record, required, recommended, advanced, output). It is front-loaded with the purpose and usage conditions. Every sentence adds value, and the structure aids readability. Could be slightly more concise, but it remains effective. Score 4.

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 23 optional parameters and no output schema, the description covers the tool's purpose, usage guidelines, key parameter semantics, auto-detection behavior, output format, and related tools. It is sufficiently complete for an agent to understand when and how to invoke the tool. Score 4.

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 add meaning beyond parameter names. It does: it explains that `summary` and `detail` are required, `tags` accepts JSON list or string, `impact` is 0.0-1.0, and `scope` has auto/project/user options. It instructs that most other fields are auto-detected. Although not all 23 parameters are individually described, the description prioritizes the most important ones and covers their semantics well. Score 4.

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 'Persist a non-obvious discovery so future agents inherit the finding.' It uses a specific verb ('persist') and resource ('non-obvious discovery'), and it distinguishes the tool from siblings like `trw_recall` (retrieve) and `trw_learn_update` (update). The purpose is crystal 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 provides explicit 'Use when' conditions and a list of what qualifies as a valid learning. It also specifies what not to record ('Routine observations...'). It includes 'See Also: trw_recall, trw_learn_update' to guide alternative tool selection. This is exemplary 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?

No annotations are provided, so the description carries full burden. It details effects: updating status stops entries from appearing in recall, feedback affects ranking, and the supersedes parameter closes prior validity windows. It also describes the output shape. However, it lacks information on authorization or rate limits, which would be needed for full 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 concise, with a clear opening sentence followed by bullet points for usage. It is well-structured and front-loaded with the core purpose. No extraneous information is present.

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 19 parameters and no output schema, the description covers key aspects: when to use, effects of parameters (especially supersedes and feedback), and the output structure with status and error fields. However, it could mention idempotency or whether updates are partial or replace all fields, but the schema descriptions handle most parameter details.

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 89%, so baseline is 3. The tool description adds value by explaining how parameters like feedback affect recall ranking and how supersedes closes validity windows. This context goes beyond the schema descriptions, justifying a 4.

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 'Update an existing learning — status, fields, or feedback signal' with specific verb and resource. It lists concrete use cases (e.g., fixing a learned issue, marking obsolete, sharpening details) which make the purpose unmistakable.

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 lists when to use the tool with bullet points: status transitions, detail refinement, feedback adjustment. This provides clear context for invocation, even though it doesn't explicitly mention when not to use it or alternatives.

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

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

Tool has no description.

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?

Tool has no 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?

Tool has no 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?

Tool has no description.

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?

Tool has no description.

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?

Tool has no description.

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 discloses writing to an audit log and returning a dict with proposal id and content hash. However, it does not mention idempotency, reversibility, or required permissions, leaving gaps for an agent.

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 four sentences, front-loaded with the action, then usage condition, then return format. Every sentence adds value, no 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?

Given the tool has 3 parameters and no annotations, the description explains purpose and return but fails to describe optional parameters and prerequisites (e.g., proposal must exist and be promoted). Output schema exists but doesn't fully compensate.

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%, yet the description explains none of the three parameters. It only implies 'proposal_id' as the key parameter but omits 'state_dir' and 'audit_log_path', which have defaults and anyOf types that need clarification.

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 'Roll back a previously promoted meta-tune proposal' with a specific verb and resource. It distinguishes this tool from siblings by focusing on a unique operation not evident in other tool names.

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

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

Explicitly says 'Use when a promoted candidate is causing regressions and you need to restore prior surface content while writing an audit log entry.' Provides clear context for use but does not mention when not to use or alternatives.

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

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

With no annotations, the description carries full burden. It discloses 'NEVER raises' and 'Tier-gated', which are useful behavioral traits. However, it does not explicitly state whether the tool is read-only or has side effects, leaving some ambiguity.

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, each adding value: purpose, usage, and traits. It is concise, front-loaded, and contains no fluff.

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 explains the output and usage adequately, but fails to cover the input parameters. Given that schema coverage is 0%, this is a notable gap, though the tool is simple and params are optional.

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 two parameters (cache_dir, repo_root) with no descriptions (0% coverage). The description does not mention or clarify these parameters, so it adds no meaning 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 clearly states the tool returns a 'RiskOrderingComparison' for the current SHA, and specifies it compares two persisted risk-ordering sidecars. This is specific and distinct from siblings like trw_cross_repo_ordering.

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 'Use when comparing two persisted risk-ordering sidecars', providing clear context. It also mentions 'Tier-gated' and 'NEVER raises', which guide availability and error behavior, though no explicit 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 provided, the description fully discloses behavioral traits: all probes are read-only and fail-open individually. It details what each signal checks (sync_push, graph_edges, etc.) and the output structure, leaving no ambiguity about safety or 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?

Efficient and well-structured: front-loaded with purpose, followed by usage conditions, then detailed signal checks. Every line earns its place without 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?

Despite no output schema or annotations, the description fully covers the return format (degraded flag, advisory, per-signal details) and documents all five signal checks. Complete for a parameterless, read-only probe tool.

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

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

Input schema has zero parameters (100% coverage trivially), so the description adds all necessary meaning. It explains the structured output and per-signal sub-dicts, which is entirely 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?

Description clearly states it probes five specific pipeline signals and returns a structured report with degraded flag and advisory. Tool name aligns with purpose, and the detailed breakdown distinguishes it from sibling tools like trw_probe or trw_status.

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

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

Provides explicit when-to-use scenarios: when trw_session_start returns a pipeline_health_advisory, or for routine health checks. Lacks explicit when-not-to-use or alternatives, but the guidance is clear and actionable.

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 exist, so the description fully carries the burden. It details outputs (12 sections, confidence scores, traceability), auto-update behavior for INDEX.md/ROADMAP.md, auto-generation of title and sequence, and scaling of validation based on risk_level. Does not explicitly mention whether it overwrites existing files or is purely append, but the creation context implies non-destructive 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?

Well-structured with clear sections: purpose, usage conditions, parameter list with bullets, output description, example, and cross-reference. No extraneous sentences; each part serves a distinct role.

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 no annotations and no output schema, the description covers all needed context: inputs, processing behavior, output structure (with fields enumerated), side effects (catalogue sync), and an illustrative example. It is fully self-contained for an agent to understand and invoke correctly.

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

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

Schema has 0% description coverage, but the tool description provides detailed semantic context for all 6 parameters including default behavior, valid values, and impact on output. For example, 'category: one of CORE, QUAL, INFRA...' and 'title: auto-generated from input_text when empty'—adds meaning far 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 clearly states it generates an AARE-F compliant PRD from a feature description. It lists specific use cases and distinguishes itself from sibling tool 'trw_prd_validate' via the 'See Also' section, providing a specific verb+resource+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?

Explicit 'Use when' bullets outline appropriate contexts: having a feature request, before writing code for P0/P1/P2 features, and need for structured PRD with auto-increment IDs. Also implies when not to use via reference to 'trw_prd_validate'.

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 exist, so the description must carry full burden. It only states the tool diffs files with a specific focus; it omits whether the tool is read-only, whether it modifies anything, required permissions, output format, or side effects. Minimal behavioral 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?

Two concise sentences plus a bullet list. Front-loaded with purpose. No unnecessary words or repetition. 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?

No output schema and only two parameters. Description lacks output format (e.g., text diff, structured change report), safety information, or prerequisites. Incomplete for an AI agent to fully understand invocation outcomes.

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

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

Schema coverage is 0% for parameter descriptions. Parameter names 'before_path' and 'after_path' imply order but the description does not clarify path format (local, repo, relative) or constraints. No added semantic value beyond 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?

Clear verb+resource: 'Diff two PRD files' with a specific focus on requirements, metrics, and acceptance-gates. Distinguishable from sibling tools like trw_prd_create and trw_prd_validate, though not explicitly differentiated.

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

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

Explicit 'Use when' bullets provide two clear scenarios: reviewing changes between versions and auditing evolution. Lacks when-not-to-use or alternative tool mentions, but the context is sufficient.

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 fully discloses that the tool runs structure compliance, content quality, AARE-F compliance, and ambiguity analysis. It also notes that it catches issues that would cause rework. It does not mention side effects, auth needs, or rate limits, but for a read-only validation tool, 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 well-structured with clear sections for purpose, use cases, what it checks, input/output, and an example. It is concise yet complete, with no wasted sentences.

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 there is no output schema, the description provides a detailed breakdown of the return structure, including enum values for quality_tier and a crucial note that no 'PRODUCTION' tier exists. This level of detail compensates for the lack of an output 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?

With only one parameter and 0% schema description coverage, the description adds meaning by stating 'path to the PRD markdown file (required).' There is a minor inconsistency: the schema has a default empty string and no required field, but the description still provides useful context.

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 scores a PRD against a V2 validation suite before implementation. It distinguishes from siblings like trw_prd_create and trw_prd_diff by focusing on validation rather than creation or diffing.

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 'Use when: A PRD just landed...' and 'You want ambiguity / completeness / traceability gates checked in one call.' It does not mention when not to use or alternatives, but the context is clear enough for an agent to decide.

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 exist, but the description fully covers behavior: it is best-effort (sub-step failures populate status without raising), explains output fields, and notes parameters are conversation-derived. There is no contradiction with absent 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 well-structured with clear sections (purpose, usage, parameter explanation, best-effort note, output format). Every sentence is informative, and it is front-loaded with 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 no annotations, no output schema, and high complexity, the description is extremely complete: it covers purpose, usage context, parameter semantics, behavior, and output structure. No significant 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?

Schema coverage is 0%, yet the description explains both 'directive' and 'context_anchor' in detail: their purpose, why they cannot be auto-derived, and that they are optional. This adds substantial meaning 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 clearly states 'Capture a safety checkpoint before the context window compacts' with a specific verb and resource. It differentiates from siblings like 'trw_checkpoint' and 'trw_session_start' by focusing on the pre-compaction scenario.

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

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

Explicit 'Use when:' conditions are provided: invoked by PreCompact hook or when compaction is suspected. This gives clear guidance on when to invoke the 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?

No annotations are provided, so the description carries the full burden. It details the sandbox environment (SAFE-001, subprocess, seccomp, no-network default), resource bounds (timeout_s, memory_mb), return type (ProbeResult with verdict), budget enforcement, and caching. It does not mention potential side effects or cleanup, which prevents a perfect score.

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 paragraph. It starts with the primary purpose, then usage context, execution details, and return value. Information is front-loaded. Some phrasing could be more concise (e.g., 'a typed...comes back'), but overall it 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?

Given 8 parameters (2 required), 0% schema coverage, and an output schema (exists but not detailed), the description covers main usage, sandbox, return type, budget errors, and caching. It mentions error returns but lacks specifics on error handling or edge cases. Overall, it is fairly complete for a probe tool.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions key parameters (command, timeout_s, memory_mb, etc.) but does not explain each in detail or provide format constraints. For example, it does not clarify the 'run_id' parameter's purpose or the valid values for 'planning_mode'. While context is given, precise semantics are lacking.

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 purpose: 'Run a bounded, sandboxed experiment to resolve a disputed plan assumption.' It specifies the action (run experiment) and the resource (disputed assumption), and distinguishes from sibling tools by referencing the PLAN phase and plan branch disagreements.

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

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

Explicitly states when to use the tool: 'during the PLAN phase, two plan branches disagree on a load-bearing, empirically resolvable claim a rubric cannot adjudicate.' Provides an example. However, it does not specify when not to use it or suggest alternative tools, which slightly lowers the score.

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 description carries full burden. It explicitly states 'Read-only — never mutates budget state' and discloses the return structure. It does not mention rate limits or prerequisites, but for a read-only report, 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 concise with three sentences, front-loaded with purpose, and structured into two clear paragraphs. No wasted words.

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 read-only tool with 2 optional params and an output schema, the description covers purpose, use case, return structure, and behavior. The output schema exists so return value details are not 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?

Schema description coverage is 0%. The description only mentions 'planning_mode' in the return context, not its input meaning. Parameters 'run_id' and 'planning_mode' are not explained, leaving the agent to rely on defaults without guidance on when to override.

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 reports live probe budget usage for a session (read-only), with a specific verb and resource. It distinguishes from siblings like 'trw_probe' and 'trw_status' by focusing on budget usage and mentioning FR-10.

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 describes when to use ('detect runaway probe usage before it becomes cost/latency creep') and states it's read-only. While it doesn't name alternatives, the context is clear enough for an agent to choose this over similar 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 fully discloses behavior: it resolves a 6-layer chain, reports per-field attribution with override chain, and on error returns a fail-open payload (never raises). This transparently covers the tool's operational characteristics.

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: a clear opening statement, separate 'Use when' section, input list, and output definition. No unnecessary words; all sentences add value. It is concise yet comprehensive.

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 annotations and output schema, the description fully covers input parameter semantics, output structure (dict with fields, layers_applied, etc.), and error behavior. It is complete for an agent to use correctly.

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

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

Despite 0% schema description coverage, the description explains each parameter's purpose (e.g., 'override the inferred domain layer'), their optionality, and hints at values (e.g., 'frontend'). This adds significant 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 explicitly states the tool's function: 'Explain the resolved profile's per-field layer attribution.' It uses a specific verb ('explain') and resource ('resolved profile's per-field layer attribution'), and details the output (effective value, origin layer, override chain). This clearly distinguishes it from sibling tools, which cover other aspects of the trw ecosystem.

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 two explicit use cases: 'when a surprising ceremony/review/build-check gate fires' and 'when auditing the policy in force for the session.' It also notes that all inputs are optional and inferred when omitted, guiding the agent on when to override defaults. No when-not guidance is given, but the specificity is sufficient.

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 full behavioral disclosure burden. It omits traits like read-only nature, ordering, pagination, or rate limits, providing insufficient transparency for a read 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 a single front-loaded sentence that efficiently states the primary action. However, it could be slightly expanded to include key details 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?

Given no output schema and simple parameters, the description does not explain return values or what 'merged cross-emitter event view' entails, leaving notable gaps for a query tool.

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

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

Schema coverage is 100%, so the schema already describes both parameters well. The description adds no additional meaning beyond stating 'session', which is already covered by the schema's session_id description.

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 'Return a merged cross-emitter event view for a session' clearly states the verb and resource, distinguishing this tool from siblings like trw_recall or trw_probe by specifying 'merged cross-emitter event 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?

The description implies usage for querying events for a session but does not explicitly state when to use this tool versus alternatives or provide exclusions, leaving usage guidance implicit.

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 burden. It discloses ranking logic (relevance, utility, context boosts), time-travel recall, auto-compact for wildcards, anti-collapse guard, tier inclusion behavior, and output shape. This is comprehensive for a retrieval 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 concisely structured: purpose sentence, bulleted use cases, ranking explanation, output format. Every sentence adds value with no 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?

Given the complexity (13 parameters, output schema exists), the description covers purpose, usage, ranking, and output. It is complete for an agent to decide when and how to use the tool effectively.

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

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

Schema description coverage is 100%, so baseline is 3. The main description adds contextual insight (e.g., ranking, compact mode auto-enable) but does not significantly extend parameter semantics beyond the already thorough 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 'Retrieve prior learnings relevant to your current task,' which is a specific verb+resource. It distinguishes from siblings by mentioning 'See Also: trw_learn, trw_session_start' and providing unique use-case bullets.

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 lists three when-to-use scenarios (unfamiliar area, suspected recurring bug, narrow slice before subagent) and mentions alternative tools. This provides clear guidance on appropriate contexts.

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, but the description effectively discloses key behaviors: single-use grant, telemetry logging, TTL capped at 5 minutes regardless of ttl_seconds. It does not mention error handling or results of unused grants, but core behavioral traits are well covered.

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

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

The description is three sentences long, each sentence providing essential information without redundancy. It is front-loaded with the core purpose, then guidelines, then parameter nuance. No wasted words.

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, the description adequately explains input parameters and behavior. It mentions session scope, logging, and TTL limits. It assumes domain knowledge about 'phase-masked', which is acceptable for a specialized tool. Minor gap: it doesn't describe what happens after the grant is used or expires.

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 100% description coverage for its three parameters. The description adds value by clarifying that the grant is single-use and the TTL is capped at 5 minutes, which goes beyond the schema's default and maximum description. This helps the agent understand the effective behavior.

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 purpose: to grant single-use access to a phase-masked tool. The verb 'grant' and resource 'phase-masked tool access' are specific, and the description distinguishes this tool from siblings by focusing on access control rather than actions.

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 specifies when to use the tool: for genuine cross-phase or emergency-debug needs when a tool is masked. It also advises caution due to telemetry logging. While it doesn't explicitly list alternatives, the context of siblings makes the usage clear. Slight gap in mentioning when not to use.

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 burden. It mentions persistence (writes review.yaml) and describes modes, but does not disclose side effects, authentication needs, or rate limits. It provides basic behavioral context but lacks depth.

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 (summary, use when, modes, input, output, example) and front-loads the main action. It is somewhat lengthy but every section adds value. Could be slightly more concise.

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 no output schema, the description details output fields and covers parameter behavior and modes. It provides an example. For a tool with 5 parameters and multiple modes, it is fairly 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%, but the description explains all parameters (findings, run_path, mode, reviewer_findings, prd_ids) with types and usage context. It compensates well for the lack of 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 the tool computes a code-review verdict and persists a review.yaml artifact. It specifies modes and outputs, but does not explicitly differentiate from sibling tools like trw_prd_create or trw_prd_diff. However, the modes (manual, auto, cross_model, reconcile) provide implicit 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?

The 'Use when' section provides specific scenarios (gating PR, pre-collected findings, spec-vs-code drift) and lists four modes with contexts. It does not explicitly state when not to use, but the guidelines are clear and actionable.

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 exist, but the description fully discloses behavioral traits: compact vs verbose payload, partial-failure resilience, and output structure, compensating for the lack of 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 well-structured with clear sections, bullet points, and an example. Every sentence contributes value, making it informative yet concise.

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 simplicity (two optional params, no nested objects, no output schema), the description thoroughly covers inputs, outputs, edge cases, and behavior, leaving no 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?

Both parameters (query and verbose) are explained in detail, covering default behavior, wildcard, and compact/verbose differences, adding substantial meaning beyond the schema which has 0% 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 that the tool loads prior learnings and active runs for full context, and distinguishes itself from siblings like trw_init and trw_recall via a 'See Also' section.

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

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

Explicit use cases are listed: starting a new session, resuming after compaction, switching tasks, with guidance on when to use and partial-failure resilience, plus references to alternative 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 exist, so the description must fully disclose behavior. It states 'without executing them' (safe, read-only) and 'Rank eligible' (a ranking operation), but doesn't explain 'eligible' criteria, side effects, or returned data shape.

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

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

Two sentences—no redundancy, front-loaded with action, and straight to the point. 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?

5 parameters and no output schema. The description covers core purpose but omits details about return format (e.g., just rankings? scores?) and leaves 'eligible' undefined. Adequate but with notable 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 100% with adequate parameter descriptions (e.g., mode enum, query, active_cap). The tool description adds 'Rank eligible SKILL.md files' but doesn't enrich parameter meaning beyond the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'Rank eligible SKILL.md files without executing them.' The verb 'Rank' and resource 'eligible SKILL.md files' are specific. This distinguishes it from sibling tools like trw_adopt_run, which likely executes.

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

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

Explicitly advises 'Use when an agent needs safe skill recommendations from explicit SKILL.md paths before invoking any workflow.' This provides a clear context and purpose, though it could explicitly state 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 description carries full burden. It indicates read-only behavior by saying 'report' and describes auto-detection of run_path. However, it does not explicitly state that the tool is non-destructive or address permissions/rate limits, which would elevate 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?

Description is well-structured with clear sections: main purpose, use cases, input, and output. It is front-loaded with the core action and contains no extraneous 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?

Given only one parameter and no output schema, the description lists expected output fields and provides usage context. It could mention error conditions (e.g., run not found) but is otherwise adequate for a status reporting tool.

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

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

The sole parameter run_path is explained: 'path to the run directory. Auto-detects from pin if None.' This adds meaning beyond the schema type and default, clarifying behavior when omitted.

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 the tool reports the active run's phase, wave progress, shard state, and last activity. It uses a specific verb ('report') and resource ('active run's state'), and distinguishes itself from sibling tools like trw_checkpoint or trw_adopt_run.

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

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

Explicitly provides two use cases: resuming after context compaction/session restart, and deciding whether to checkpoint/advance/re-delegate. It does not mention when not to use or alternatives, but the provided guidance is clear and actionable.

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 discloses key behaviors: automatic metadata attachment, error handling that never raises, and output format. This adds substantial value beyond the schema.

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, front-loads purpose, and each sentence adds value. Slightly verbose but still 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 description covers input, output fields, error handling, and automatic metadata. With an output schema present, it is complete for the 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?

Despite 0% schema description coverage, the description explains each parameter in detail: category options, subject constraints, message length, optional contact_email, and metadata limits. Fully compensates for 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 the tool submits a memo to the TRW maintainer and lists specific use cases (bug, installation problem, feature request, etc.). It distinguishes itself from the sibling tools, none of which are for feedback submission.

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 includes a 'Use when:' section with explicit scenarios, providing clear context. It does not list exclusions or alternatives, but the positive guidance is sufficient.

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 return format (dict with classification, surfaces, rationale) but does not explicitly state that the operation is read-only or safe, nor mention any side effects or authorization needs.

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

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

The description is very concise: two sentences for purpose and usage, plus a clear return format. No wasted words, and the key information 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 simple classification tool with one parameter, the description covers the return format but lacks clarity on the input path and any prerequisites. It is adequate but not fully complete given the missing parameter details.

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 'path' lacks description in the schema (0% coverage). The description only mentions 'candidate path' in the context of usage but does not define what the path represents (file path, URL, etc.), leaving ambiguity.

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 'Classify a meta-tune surface as control vs advisory,' providing a specific verb and resource. While it doesn't explicitly differentiate from siblings like trw_surface_diff, the purpose is unambiguous and 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?

The description includes a concrete use case: 'Use when you need to know whether a candidate path is governed by the SAFE-001 control surface registry before promoting a meta-tune proposal.' However, it lacks when-not-to-use or alternative 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?

Despite lacking annotations, the description discloses the diff logic by explaining that 'changed' entries appear in both snapshots with different content_hash values, and it lists the output fields. This provides clear behavioral transparency about the comparison criterion and result structure.

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 highly concise at two sentences: the first states the overall purpose and the second details the output format. Every word earns its place with no redundancy, and the key information 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 tool with two parameters and no output schema, the description adequately explains core functionality and output structure. However, it omits context such as error behavior when snapshots are missing or prerequisites for the input IDs, which would improve completeness.

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

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

The input schema includes two required string parameters (snapshot_id_a, snapshot_id_b) with no descriptions, and the tool description adds no clarification about them. Schema coverage is 0%, so the description should compensate but does not, leaving parameter semantics largely implicit.

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 performs a 'structured diff between two surface snapshots' and specifies the return format with 'added, removed, changed' lists of surface_id strings. The purpose is specific and actionable, though it does not explicitly differentiate from sibling tools like trw_surface_classify.

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, nor are there any prerequisites or exclusions mentioned. The description is purely functional without contextual usage advice.

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 states that the tool 'return structured errors' but does not detail what 'structured errors' means, whether it is read-only, or if any side effects occur. The description is adequate but lacks depth on behavioral specifics.

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 consists of two concise sentences, front-loaded with the core action, and contains no unnecessary words. Every sentence 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 is simple with one parameter and no output schema. The description explains the purpose and usage context well. However, it does not describe the return format or error structure, which would be helpful for a validation tool. Still, it is mostly 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 coverage is 100% for the single parameter 'data', and its schema description is 'Candidate AgentWorkEvidence JSON object.' The tool description adds the same wording, so it provides minimal extra meaning beyond the schema. With high coverage, baseline is 3.

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 validates an AgentWorkEvidence candidate and returns structured errors. It uses a specific verb ('validate') and resource ('AgentWorkEvidence candidate'), and it distinguishes itself from siblings like 'trw_agent_work_evidence' by focusing on validation rather than creation or retrieval.

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 explicit context for when to use: 'Use when an external producer or fixture needs schema validation before evidence is accepted...' This gives clear guidance, though it does not mention when not to use or list alternative tools.

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