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

Annotations declare destructiveHint=true and idempotentHint=false, and the description corroborates by detailing what gets overwritten (Application state, __PRIOR_STEP, cleared sub-runs). It adds behavioral context beyond annotations: the Application is rebuilt via factory, sub-runs are cleared, and a fork_at marker is appended to history. Rich disclosure of side effects.

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

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

The description is front-loaded with the core purpose, then details mechanics, then refusal conditions in bullet form. The bullet list of refusals is efficiently structured. It's somewhat long but every sentence carries substantive technical content; the docstring format is appropriate for the complexity of the tool.

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

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

For a complex, destructive branching tool with 2 optional params, 0% schema coverage, and no output schema, the description is remarkably complete. It covers the full lifecycle: source identification (seq/sequence_id), the rebuild-and-overwrite mechanics, sub-run clearing, marker appending, and all refusal edge cases. The agent can safely decide when to invoke this without needing additional context.

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

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

Schema coverage is 0% (neither parameter is described in the schema), so the description must compensate. It explains that sequence_id is the seq field on a theodosia://history entry, that seq is an alias, and that sequence_id wins if both are given. This adds meaningful semantic value beyond the bare schema, though it doesn't cover the nullability/default semantics in detail.

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

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

The description clearly states the tool 'Rewinds the session to the state captured after history[seq=N]', uses the specific verb 'fork'/'rewind' with a resource (session state at a prior step). It distinguishes from siblings like step, reset_session, fork_from_past by focusing on 'branch this session' from a prior step within the current session's history.

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 refusal conditions (shared-app mode, out-of-range seq, refusal target, fork/reset marker targets), giving clear when-not-to-use guidance. It also explains the difference between sequence_id and the seq alias for copy-from-history. This substantially differentiates usage from 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?

Annotations declare destructiveHint=true and idempotentHint=false, so the mutation profile is already partially disclosed. The description adds substantial value by explaining the three-tier source resolution mechanism, the partition_key default behavior matching Burr's convention, and the explicit refusal conditions. No contradiction with 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?

Well-structured with clear numbered and bulleted sections (three-tier resolution, use cases, refusal cases). Each section earns its place. Slightly verbose in the state-loader description but organized effectively with front-loaded purpose statement and scannable bullet points.

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 moderately complex fork/resume operation with 3 parameters and no output schema, the description is complete. It covers source resolution, when to use, when it refuses, partition_key nuances, and the app_id/sequence_id tracking workflow. The refusal conditions and use-case guidance make this fully actionable for an agent.

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 carries the full burden for parameters. It explains partition_key semantics ('defaults to empty string, matching Burr's default; pass it explicitly when your persister uses partitioned storage') and references app_id/sequence_id in the refusal conditions. app_id is implied as the target session identifier. This compensates well for the 0% schema coverage.

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

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

The description clearly states the tool 'Resume a past Burr run by loading persisted state' with a specific verb (resume/fork) and resource (a persisted past run/session). It distinguishes from siblings by clarifying it forks from any persisted past run, not just the current session's in-memory history, and lists explicit refusal cases which differentiate it from fork_at.

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 an explicit 'Use this for' section listing concrete scenarios (resuming across server restarts with app_id tracking, forking from any persisted past run). Also provides a 'Refuses when' section detailing exclusion conditions (shared-app mode, no state_loader/LocalTrackingClient, non-existent app_id/sequence_id), giving clear guidance on 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?

Annotations provide readOnlyHint=true, and the description's return format detail (uri vs uri_template distinction with placeholders) adds useful behavioral context beyond annotations. However, it does not describe pagination, ordering, or whether resource metadata is complete — meaningful gaps for a listing 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 three short sentences with zero waste. First sentence states the purpose directly, second explains return format, third clarifies the template vs static distinction. Everything earns its place.

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

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

Given 0 parameters, a readOnly annotation, and an output schema present, the description covering purpose, return format, and the static-vs-template distinction is well-calculated for completeness. The addition of a brief note about template placeholders like {name} makes the return data self-explanatory.

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

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

The tool has 0 parameters, so the schema already covers 100% of parameter documentation. The description adds value by explaining the output structure (uri vs uri_template fields), which serves as the semantic payload. With no params, baseline 4 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 uses a specific verb+resource construction: "List all available resources and resource templates" — clearly states what the tool returns. It distinguishes itself from siblings like read_resource by covering the enumeration/listing function rather than fetching a single resource.

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 it is the tool to enumerate available resources, but does not explicitly contrast with read_resource (which fetches a specific resource) or give when-to-use/not-use guidance. Context is clear but no exclusions or alternative tool names are explicitly mentioned.

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

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

Annotations already declare readOnlyHint=true, and the description adds useful context about the return format (string content, base64 for binary). It doesn't contradict annotations. It could add more behavioral detail like what happens for nonexistent URIs or error conditions, but with readOnlyHint covering the safety profile, this is adequate.

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 concise with clear paragraph breaks for scope (static vs templated) and return format. Every sentence earns its place. Slightly more detail could be trimmed but it's well-structured and 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 a single parameter, a full output schema, and readOnlyHint annotation, the description covers the essential usage guidance. It explains the return type and binary encoding behavior which supplements the output schema. Complete for a simple read tool with good annotation coverage.

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

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

Schema description coverage is 100%, so the single uri parameter is fully documented in the schema. The description adds context about how to fill the URI for static vs templated resources, which adds value 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?

The description clearly states the tool reads a resource by URI, distinguishing it from list_resources (which lists rather than reads). It also differentiates static vs templated resource handling. It doesn't explicitly name the sibling alternative but the verb+resource+behavior is 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 explains when to use it for static vs templated resources, providing explicit guidance on how to construct the URI in each case. However, it doesn't explicitly state when NOT to use it or mention alternatives like list_resources for discovery.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true. The description adds substantial context beyond these: it clears sub-runs, appends a marker to history while preserving prior entries (critical non-destructive-to-history detail), and details the shared-app refusal behavior. This meaningfully augments the annotation-provided safety profile.

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

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

The description is well-structured and front-loaded with the core purpose, then layered with behavioral details and usage constraints. Every sentence earns its place—purpose, side effects, audit-trail semantics, and the shared-app limitation are each addressed without redundancy. Formatting with the reset marker example is illustrative, not wasted.

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

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

For a zero-parameter, no-output-schema tool with rich annotations, the description is nearly complete. It covers side effects, history semantics, and usage constraints. The only minor gap is not describing the success/failure return behavior, but with no output schema and clear side-effect documentation, this isn't a significant omission. It sits below a 5 because it doesn't describe what the client receives upon success.

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 parameters, the baseline is 4. The description adds no parameter semantics (there are none), and the effectively 100% schema coverage (empty schema) requires no compensation. The score reflects the strong baseline for a zero-parameter tool.

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 resets the session's FSM to its entrypoint, with specific verbs and a distinct resource. It distinguishes itself from siblings—read_resource, step, fork_at, fork_from_past, list_resources—by focusing on resetting state rather than reading, stepping, or forking.

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

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

The description explains when it's appropriate (factory mode) and explicitly when not to use it (shared-app mode), naming the alternative (per-session isolation/factory mode). However, it doesn't name a specific sibling tool as the alternative, which would push it to a 5.

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

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

The destructiveHint annotation already signals this tool mutates state. The description adds substantial behavioral context beyond annotations: it documents error behavior (invalid_transition with valid action list), details non-blocking actions that degrade gracefully (doc_lookup, splunk_preflight, detect_anomalies), describes fallback behaviors (generate_script, fix_script, run_test with timeout), and reveals the read_diff -> analyze failure path. It does not explicitly state that advancing the FSM mutates/destroys prior state, but given the annotation covers destructiveness, the additional context about degradation and fallbacks earns a 4.

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

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

The description is extremely information-dense and front-loads the core mechanism clearly, but it is very long, containing an exhaustive action catalog and 25-transition state table that could arguably live in a linked resource rather than the description. Every sentence carries useful information, so it earns credit for density, but the sheer size makes it hard to scan quickly for the JSON-invoking agent.

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

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

For a complex 16-action state machine with 2 parameters, an output schema, and 100% schema coverage, the description is remarkably complete. It details each action's purpose, prerequisites, fallback behaviors, and the full transition graph. An output schema exists to explain return values. The only minor gap is that some action entries are truncated mid-sentence ('analyze: The writer phase' / 'screen: The auditor phase' cuts off), suggesting incomplete authoring of the final three entries.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by detailing action-specific input expectations ('Pass intent for natural-language mode, or just repo_path/ref for diff mode', 'Pass VUs + duration'), clarifying the inputs format (object canonical vs JSON-encoded string accepted), and explaining how invalid action values are handled. This enriches several parameters meaningfully beyond the bare schema definitions.

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 advances an FSM by one transition, taking an action name to execute. It provides an extensive, well-structured catalog of all 16 actions with specific descriptions of what each does, distinguishing this tool as a state-machine driver rather than a simple operation. The verb+resource framing is specific and unambiguous.

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

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

The description explicitly lists all valid actions with detailed when-to-use guidance for each (e.g., 'Start a run. Pass intent for natural-language mode...'), documents when transitions are allowed via the full transition table, and explains the failure mode ('returns invalid_transition error with the list of actions actually allowed right now'). It also explicitly tells users to consult theodosia://next for expected inputs, providing clear usage context.

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