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?

The readOnlyHint annotation already indicates the tool is non-destructive. The description adds valuable context beyond this by explaining the output structure (JSON with resource metadata) and the key distinction between static 'uri' fields and templates with 'uri_template' placeholders. This extra detail about the return format and resource types exceeds what the annotation provides, though the read-only behavior itself is not elaborated further.

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, consisting of two short sentences. It front-loads the primary action and object ('List all available resources and resource templates') and then provides necessary detail on return format and resource types without any redundant or vague phrasing. Every sentence adds meaningful content.

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

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

Given the tool's simplicity (no parameters, clear output schema present), the description is sufficiently complete. It explains what the tool returns (JSON metadata) and the critical distinction between static and template resources, which is essential for understanding the tool's behavior. The presence of an output schema means the description does not need to enumerate all return fields, and it covers the key context an agent would need to use the tool correctly.

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

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

The tool has zero parameters, and the schema coverage is 100% (vacuously). There are no parameter semantics to explain, so the description does not need to add any meaning. The description fully aligns with the input schema, and there is no ambiguity or missing parameter information.

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

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

The description clearly states the action ('List') and the target ('all available resources and resource templates'). It distinguishes between static resources and templates, making the purpose unambiguous even without opening the schema. This is a precise, specific statement of what the tool does.

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

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

The description does not explicitly state when to use this tool over siblings like read_resource or legal_list_laws. It implies that this is for discovery (listing all resources), but it does not provide direct guidance on selection criteria. The information about static vs. template resources is helpful but does not constitute explicit usage direction.

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 readOnlyHint annotation is consistent with the described read-only behavior. The description adds useful details about return content and base64 encoding, going beyond the annotation without contradicting it.

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

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

The description is compact and well-structured, with no unnecessary words or repetition. It delivers all essential information in two 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?

For a simple read operation, the description is complete: it covers input format, output type, and encoding. No further details are needed for correct usage.

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 'uri' is described in the schema, but the tool description adds important nuance about static vs. templated URIs, which is not present in the schema. This additional guidance improves parameter understanding.

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

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

Clearly states the verb 'Read' and the object 'resource by its URI.' It distinguishes from sibling tools such as list_resources (listing) and legal_* tools (specific legal actions) by focusing on reading 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?

Provides guidance on static vs. templated URIs and explains output encoding. Does not explicitly contrast with alternatives, but the purpose is straightforward and the instructions are sufficient for correct invocation.

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.