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

Annotations already declare destructiveHint and idempotentHint, but the description adds specifics: rechecks snapshot/config revisions, freshness, automation modes, action limits; records one audit event; retries return original result with idempotent_replay=true without state change; unknown or changed proposals fail. No contradictions 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?

The description is well-structured with clear sentence separation, front-loading the core purpose. It is slightly longer than minimal but every sentence adds important behavioral or usage context, so it 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 the output schema, annotations, and detailed description, everything an agent needs to know is covered: prerequisites, approval flow, idempotency, failure modes, and the synthetic demo scope. 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 100% with descriptions for both parameters. The description adds value by explaining that proposal_id must be the exact one from prepare_action and that confirmation is only needed in review mode, beyond what the schema states. This justifies a score above the baseline of 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 the tool's verb and resource: 'Execute an existing proposal' and scopes it to 'synthetic demo state only'. It also differentiates from siblings by referencing prepare_action and the ESPN companion for live submissions, so an agent can distinguish it from related tools.

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

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

It explicitly says to first call prepare_action and obtain approval when requires_confirmation is true. It also states when not to use it ('Use the ESPN companion for live submissions') and describes retry and failure conditions, giving clear usage context.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial context beyond that: it enumerates the event types recorded (snapshot imports, configuration changes, prepared proposals, completed demo actions), clarifies the semantic nuance of action_prepared events (preparation vs. execution), and notes that the tool works before a snapshot is loaded. This goes well beyond the annotations and meaningfully informs the agent about behavior and scope.

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 purpose, then delivers the return format, event types, a nuance, and timing in a compact series of sentences. Every sentence earns its place; there is no redundancy or filler. It is efficient and well-structured.

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

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

Given the tool has only one parameter, an output schema exists, and annotations cover safety, the description fills in all remaining gaps an agent needs: return field names, ordering, event semantics, and availability before snapshot load. Nothing essential is missing for correct invocation.

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

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

The schema covers the sole parameter 'limit' fully, describing its range (1–500), default (50), and ordering behavior. The description does not add any additional meaning to the parameter beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with 'Read recent audit records from this data directory without changing state,' a specific verb and resource that clearly distinguishes it from sibling tools like prepare_action or execute_demo_action. It also specifies the return fields (id, at, event, detail) and ordering, leaving no ambiguity about 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?

While no alternative tool is named, the description provides clear context for when to use it: it works before a snapshot is loaded, and it explicitly separates calculation evidence from audit history ('Calculation evidence is separate from this audit history'), implying a when-not scenario. This gives an agent enough guidance to route correctly, though it stops short of naming a specific sibling.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it states the server only executes synthetic demo actions (not real-world actions), that the response distinguishes implemented actions from verified live execution, and that the tool 'does not change saved state.' This is meaningful behavioral disclosure that helps an agent trust the tool and interpret its output correctly.

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

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

The description is compact and front-loaded with the most important usage directive. Each sentence adds distinct information: when to use, what is returned, server scope, response structure, and side-effect guarantee. It is slightly repetitive in places (e.g., 'synthetic demo actions only' and 'distinguishes implemented actions from verified live execution' both touch on the demo nature), but overall it is efficient and well-structured.

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

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

For a zero-parameter, read-only capability probe with an output schema present, the description is nearly complete. It covers when to call it, what it returns, the server's execution scope, and the no-side-effect guarantee. The only minor gap is that it doesn't explicitly describe the output schema structure, but the presence of an output schema means the description need not explain return values in detail. The mention of 'ESPN companion' and 'acceptance report' is slightly cryptic but not blocking.

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

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

The tool has zero parameters, so there is no parameter semantics burden on the description. The schema coverage is 100% (vacuously, since there are no properties). The description instead explains what the response contains, which is the relevant semantic information for a no-arg capability probe. A baseline of 4 is appropriate 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 opens with a clear directive: 'Read this server's capabilities before selecting analysis or execution tools.' It names the resource (server capabilities) and the specific verb (read), and it distinguishes the tool from siblings by stating it is a prerequisite step before choosing other tools. The subsequent sentences enumerate exactly what is returned (supported actions, automation modes, pause state, snapshot presence, revisions), which leaves no ambiguity about the tool's purpose.

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

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

The first sentence explicitly states when to use this tool: 'before selecting analysis or execution tools.' It also clarifies the server's scope ('analyzes imported data and executes synthetic demo actions only'), which helps an agent understand what capabilities to expect and when this tool is relevant. The description also notes it 'Works before a snapshot is loaded,' giving a clear precondition. While it doesn't name a specific alternative tool, the context of sibling tools (e.g., get_source_status, get_manager_config) makes the usage context clear enough.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description adds meaningful behavior: latest is null under specific stale/paused/no-result conditions, trial counters have different scopes, and the tool does not fetch observations or append calculation evidence. This gives the agent a precise model of the tool's side effects and limitations.

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

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

Every sentence contributes useful information: what it reads, what it returns, null semantics, counter scoping, alternatives, and exclusions. It is front-loaded with the core purpose and remains dense without becoming bloated.

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

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

The description is complete for an agent to decide when and how to call this parameterless read tool. It explains stale results, counter semantics, alternatives, and explicitly states what it does not do; the output schema covers the return shape.

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, so there is nothing for the description to clarify. The schema coverage is 100% and the parameterless nature is fully visible; no additional parameter semantics are needed.

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

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

The description opens with a specific verb and resource: 'Read cached results and status from the local draft monitor.' It also explicitly says it does not run a simulation, distinguishing it from simulation-producing tools like start_draft_monitor and recommend_draft.

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 clearly tells the agent when to use this tool versus alternatives: use start_draft_monitor to produce these cached results, or recommend_draft for an independent single batch. This is explicit routing guidance, not just implied context.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds value by noting it works before a snapshot is loaded and does not change saved state, reinforcing the read-only nature and providing operational context beyond the annotations. It doesn't go deeper into performance or edge cases, but for a simple read 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 four sentences with no fluff. The core purpose is front-loaded in the first sentence, followed by a list of returned content, a behavioral note, and a usage pointer. Every sentence earns its place and the structure is easy to scan.

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 an output schema present (as indicated by the context signal), the description need not detail the return structure. It covers the essential operational details: what it returns, when it can be used, and that it does not modify state. The explicit tie to update_manager_config provides the necessary workflow context. No missing information prevents an agent from calling 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?

There are zero parameters, so the baseline is 4. No parameter documentation is needed, and the description adds no irrelevant detail. It fully satisfies the parameter-semantics requirement by having no parameters to explain.

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

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

The description opens with a specific verb and resource ('Read the full current configuration and its config_revision'), then enumerates the returned content (strategies, automation presets, per-action modes, pause state, user limits). It clearly distinguishes itself from siblings like update_manager_config, which is a write operation, by emphasizing it reads and does not change state.

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 instructs to use this tool as the starting configuration for update_manager_config to preserve existing settings, and states it works before a snapshot is loaded. This gives clear when-to-use guidance and directly points to the complementary sibling, leaving no ambiguity about its role in a read-before-write workflow.

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

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

All four annotation hints are false, so the description carries the full burden of behavioral disclosure, and it delivers. It discloses the side effect ('Appends calculation evidence without changing rosters'), defines the status contract (status='ok' or status='incomplete'), and documents edge-case behavior (null ranks for incomplete lineups, empty list for missing lock coverage). This is substantial transparency beyond what the schema or annotations provide.

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?

Seven sentences is on the longer side, but every sentence earns its place: purpose, prerequisites, return format, two distinct edge cases, scope clarification, and side-effect disclosure plus sibling routing. The purpose is front-loaded in the first sentence, and the final sentence efficiently routes to recommend_lineup. Slightly dense, but no filler.

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

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

For a zero-parameter tool with an output schema, this description is complete. It covers purpose, prerequisites, return values (rankings, source details, warnings, input revisions), status semantics, edge cases, scope limitations, side effects, and the alternative tool. Nothing an agent needs to invoke it correctly is missing.

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

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

The tool has zero parameters and 100% schema coverage, so the baseline is 4. The description mentions the underlying data requirements ('weekly inputs for every team, verified locks') in prose, which orients the agent on what the tool needs at runtime even though no explicit parameters exist. No parameter documentation is necessary, and none is missing.

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

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

The description opens with a specific verb-resource pair: 'Compare every team's best legal weekly lineup by projected points.' It states scope (every team), what is compared (best legal weekly lineup), and the metric (projected points). It also distinguishes itself from the sibling recommend_lineup, which analyzes only the selected team, so an agent can tell them apart immediately.

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

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

The description gives explicit prerequisites: 'Requires current season data, weekly inputs for every team, and verified locks with league scope.' It names the alternative explicitly: 'Use recommend_lineup to analyze only the selected team.' It also clarifies scope boundaries — these are one-week estimates, not championship probabilities — so an agent knows when not to over-interpret the result.

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, openWorldHint=false, idempotentHint=true, and destructiveHint=false. The description adds important behavioral context beyond those: it only reads saved data, does not refresh the source or run a simulation, and requires an already-imported snapshot or demo. This is a meaningful addition that helps the agent reason about side effects and 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?

The description is made up of six short sentences that each carry distinct value: purpose, prerequisite, return fields, non-behavior (no refresh/simulation), and explicit alternative tools. It's well-structured and front-loaded, with no filler or repetition.

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 zero parameters, an output schema, and detailed annotations, the description provides all remaining context needed for correct invocation: prerequisites, main behavior, and how to route alternatives. No required information about when or how to call it is missing.

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

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

The tool has zero parameters and the schema covers all properties trivially (100% coverage). With no parameters to document, the description doesn't need to compensate for schema gaps, and it correctly adds no parameter explanation beyond stating the tool requires a snapshot or demo. Baseline of 4 applies.

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

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

The description opens with a clear, specific verb and resource: 'Check the freshness and completeness of the saved observation.' It also distinguishes the tool from siblings by explicitly noting it does not refresh the source or run a simulation, and by pointing to alternative tools for fresh data and caller-supplied replacements. This leaves no ambiguity about what the tool does and what it doesn't.

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

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

The description provides a direct precondition: 'Requires an imported snapshot or loaded demo.' It also gives explicit alternative routing: 'Use the ESPN companion for fresh HTTP season observations or browser forecast observations' and 'Use import_league_snapshot for replacement data supplied by the caller.' This tells the agent exactly when to use this tool versus when to select a different one.

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, idempotentHint=true, and destructiveHint=false. The description reinforces and extends this by stating 'Requires an imported snapshot or loaded demo' and 'This tool does not fetch new data or change saved state,' adding contextual prerequisites and confirming the non-mutating behavior. No contradictions 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?

The description is three sentences, front-loaded with the core purpose, then prerequisites, return content, and usage guidance. Every sentence earns its place; there is zero redundancy or filler. It is a model of concise, effective writing.

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 no parameters, an output schema (so return format is already defined), and strong annotations covering safety, the description fully covers prerequisites, behavioral constraints, and return content. Nothing an agent needs to invoke correctly is missing.

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

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

The tool has zero parameters, so the baseline is 4. The schema coverage is trivially 100%. The description adds no parameter details because there are none, but it appropriately lists the information returned, which is useful for the agent. No gap exists.

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 'Read' and the resource 'the selected team's roster from the saved snapshot.' It differentiates from siblings by explicitly noting it does not fetch new data or change saved state, and it names specific alternatives for other operations. The purpose is unambiguous.

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

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

The description explicitly mentions when to use this tool versus alternatives: 'Use recommend_lineup to calculate a lineup or get_source_status to check observation freshness.' It also clarifies the prerequisite of an imported snapshot or loaded demo, giving the agent clear context for 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 mark the tool as destructive, and the description adds substantial behavioral detail: it preserves observation order and draft history, retains pending submissions until reconciliation, resets configuration on league/team/season changes, increments the revision, and invalidates proposals and monitor results. It also states the atomic failure mode: 'an error without replacing state.'

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?

Seven sentences, front-loaded with the tool's purpose, and every subsequent sentence covers a distinct behavioral or failure characteristic. There is no filler, repetition, or schema duplication.

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 mutation with nested inputs, the description covers preconditions, state invariants, side effects, config reset behavior, and error atomicity. An output schema exists, so return-value details are not a gap; the description even names the key response fields.

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 parameter details are already documented in the input schema. The main prose mentions 'current snapshot revision' as a precondition, matching expected_revision, but does not add new format, syntax, or usage information beyond the schema.

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

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

The description opens with a specific verb and resource: 'Validate and save a complete league snapshot supplied by the caller.' It distinguishes itself from sibling tools by naming the ESPN companion and load_demo for how data should be obtained, making the tool's role as the importer 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?

It gives concrete usage context: use the ESPN companion for live observations or load_demo for fictional data, and use the current snapshot revision for replacement. It does not formally state 'do not use this for fetching live data', but the alternative paths and precondition are explicit enough for an agent to choose correctly.

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?

Beyond the annotations (destructiveHint=true), the description reveals the exact destructive and side-effecting behaviors: 'Stops the local draft monitor, replaces the snapshot, and resets configuration when the league changes.' It also documents what the tool does not do ('This tool does not connect to ESPN') and what it returns ('status='imported', revision, config_revision, and config_reset'). This adds substantial transparency beyond what annotations already disclose.

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

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

The description is front-loaded with the main purpose and then provides behavior, prerequisites, and return values in a compact five-sentence block. Every sentence adds useful context. Only minor improvements—like merging the prerequisite and behavior sentences—could trim it further, so it earns a 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?

Together with the rich annotations, the description gives an agent what it needs: purpose, alternatives, prerequisites, concrete side effects, and return values. It also explicitly clarifies it's not an ESPN connection. A small gap remains around what happens if the data directory contains non-synthetic state or how the 'empty or existing synthetic state' is validated, but overall it's sufficiently complete for safe invocation.

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

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

Schema description coverage is 100%, and the input schema already gives the full meaning of the 'mode' parameter ('season' for weekly tools, 'draft' for draft simulations). The description does not add additional parameter semantics beyond that; it only repeats the same concept implicitly. Baseline 3 is appropriate because the schema carries the semantic weight.

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

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

The description opens with a clear verb and object: 'Load a fictional scenario for local testing or demonstrations.' It also explicitly distinguishes its purpose from a sibling by saying 'Use import_league_snapshot for your own data.' This makes the tool's intent unmistakable and differentiates it from the surrounding tools.

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

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

The description tells the agent when to use this tool (local testing/demonstrations) and names the alternative for different data ('Use import_league_snapshot for your own data'). It also states an important prerequisite: 'Requires an empty data directory or existing synthetic state.' It lacks a comprehensive 'don't use when...' list, so it earns a 4 rather than a 5.

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

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

Annotations are sparse (all hints false), so the description carries the burden. It discloses that each call creates a new proposal and audit record (non-idempotent), which aligns with idempotentHint=false. It also explains validation checks and prerequisites, adding behavioral context beyond the annotations. It doesn't mention error handling or failure modes, but the core side effects are clearly stated.

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 lists conditions, checks, returns, side effects, and alternatives. Each sentence adds information and there is minimal fluff. It is slightly longer than strictly necessary but well-organized and efficient.

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

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

Given the tool's complexity (two parameters but a payload with three variants) and the presence of an output schema, the description covers prerequisites, validations, return contents, side effects, and usage alternatives. It doesn't explicitly address error scenarios or edge cases, but an agent has enough information to invoke it correctly and know 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?

Schema description coverage is 100%, so the schema already fully documents the action enum and each payload variant. The description adds context about validations and data requirements but doesn't add per-parameter semantics beyond what the schema provides. Baseline 3 is appropriate since the schema carries the heavy lifting.

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

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

States a specific verb ('Validate'), a resource ('synthetic action'), and an explicit non-goal ('without executing it'). It clearly distinguishes itself from siblings by naming execute_demo_action as the execution counterpart and the ESPN companion for browser/HTTP proposals, so an agent can immediately tell what this tool is and is not for.

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 prerequisites ('fresh, complete synthetic data, unpaused automation, review or automatic mode'), names the execution alternative ('Use execute_demo_action with that exact proposal_id'), and states when to prefer a different tool ('Use the ESPN companion for browser draft proposals or HTTP...'). This leaves no ambiguity about when to invoke this tool.

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

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

Annotations already mark the tool as non-read-only and non-idempotent, and the description adds meaningful write behavior ('appends calculation evidence') and clear non-behaviors ('does not estimate winning bids, does not submit claims'). It also discloses statuses (ok, incomplete, blocked). Minor gap: it does not explain what side effect appending evidence has on subsequent calls, but the disclosure is otherwise strong.

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 dense but every sentence earns its place: purpose, prerequisites, outputs, statuses, exclusions, and alternatives. It is front-loaded with the main verb and resource, though the multi-sentence structure is slightly longer than strictly necessary.

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 tool with a rich output schema, the description covers what the tool does, what it needs, what it returns, status semantics, caveats, and when to use sibling tools. The agent can confidently decide whether to call it and how to interpret its results.

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 already covers the single 'limit' parameter completely (type, default, description), so there is little for the description to add. The tool description reinforces that results are 'alternative single-player acquisitions' which clarifies what the limit applies to, but this is only incremental.

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 opens with a specific verb and resource: 'Rank alternative single-player acquisitions using the saved weekly snapshot and user limits.' It clearly scopes the tool to ranking/waiver suggestions and distinguishes it from execution-oriented siblings by noting it does not submit claims and directing live proposals to espn_prepare_season_action.

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 required inputs ('current season snapshot, verified locks, weekly projections, known budget and pending commitments'), output expectations, and error states ('incomplete for missing inputs'). It also tells the agent exactly when to prefer alternatives: 'Use prepare_action only for synthetic acquisitions that pass action checks' and espn_prepare_season_action for live ESPN acquisition.

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

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

Annotations are all false, so the description carries the full burden of behavioral disclosure. It explicitly states side effects: 'Appends a calculation evidence record, including discarded work, without changing rosters or submitting picks.' It also mentions that 'current checks revision and snapshot freshness after calculation, but does not grant action permission.' This discloses non-mutating behavior and a persistent side effect, though it does not detail whether repeated calls are safe beyond not changing rosters, which is a minor gap.

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

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

The description is compact at four sentences, with the main action front-loaded in the first sentence. It then covers alternatives, prerequisites, output/status, and side effects in a logical order. Each sentence adds meaningful information without fluff, though it is slightly longer than strictly necessary.

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, the presence of an output schema means the description need not detail return values. It covers prerequisites, alternatives, side effects, and statuses (ready, stale_snapshot, incomplete_snapshot, roster_complete). It also notes that the tool does not grant action permission, which is crucial for agents. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents both parameters. The description adds value beyond the schema by explaining seed reproducibility: 'Reuse an integer with identical inputs to reproduce the simulation. This does not remove forecast uncertainty.' It also clarifies trial limits: 'Use 1 through the configured limits.batch_trials, at most 500.' This enriches the agent's understanding of how to use the parameters.

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

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

The description clearly states the specific action: 'Run one bounded draft simulation against the current imported draft snapshot.' It also distinguishes from siblings by explicitly naming alternatives: 'Use start_draft_monitor for repeated batches or get_draft_recommendations to read that monitor's cached results.' This leaves no ambiguity about what the tool does and how it differs.

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 guidance: 'Run one bounded draft simulation' and when not to: 'Use start_draft_monitor for repeated batches or get_draft_recommendations to read that monitor's cached results.' It also lists prerequisites: 'Requires draft data with consistent pick history and full-season projections for available and selected-team players.' This is thorough 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?

The description is rich with behavioral detail: status outcomes (ok/incomplete), the edge case where unknown unchanged scores cancel improvement, the non-authorization of repairs from coverage suggestions, locked-slot preservation, and the guarantee that it appends evidence without changing the current lineup. This goes well beyond the sparse 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 long but dense: every sentence carries a distinct constraint, behavior, or alternative. It is front-loaded with the main purpose, then branches into status details, edge cases, side-effect guarantees, and alternatives. A few phrases are jargon-heavy, but nothing is filler.

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

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

Covers purpose, input sources, output statuses, edge cases (unknown scores cancel improvement), guarantees (locked slots, no lineup change), limitations (coverage gaps, no repair authorization), and alternatives (prepare_action, ESPN companion). No critical context is missing for an agent to decide and invoke 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?

The input schema is empty, so the baseline is 4. The description compensates by naming the conceptual inputs (saved snapshot, projections, locks, source age limits) and the status/error payload shape, which gives an agent enough context to invoke the tool without parameter docs.

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

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

The description opens with a specific verb and outcome: 'Optimize the selected team's known weekly projections while preserving locked slots.' This clearly states what the tool does and distinguishes it from a generic lineup generator. It also names alternatives (prepare_action, ESPN companion) so an agent can tell it apart from related tools without guessing.

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

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

The description gives clear context for when the tool is appropriate: optimizing projections while respecting locked slots.linkText It explicitly points to prepare_action for synthetic proposals and the ESPN companion for live changes. It does not explicitly say

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 (readOnlyHint=false, destructiveHint=false) say little, so the description carries the burden and delivers: it discloses the monitor waits while paused or stale/incomplete, clears obsolete cached results, appends calculation evidence including discarded batches, and explicitly states 'This tool neither reads a browser nor submits picks.' This is valuable behavioral context beyond the sparse annotations, though it could mention what happens on repeated invocation when a monitor already exists.

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?

Front-loaded with the core action, then prerequisites, then behavior, then alternatives. Each sentence earns its place and the flow is logical. Slightly long for a background-starter, but every clause adds routing or behavioral value, so nothing is 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?

With an output schema present, return values need no explanation. The description covers prerequisites, behavioral quirks (stale/paused/incomplete waits, cache clearing), non-interaction guarantees, and alternative tools. Nothing an agent needs to decide whether to call this tool and how to set it up is missing.

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

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

Schema coverage is 100%, so both parameters are already documented. The description adds behavioral nuance by explaining each batch uses the latest imported snapshot and that batch duration adds to the interval, but it doesn't significantly extend meaning beyond the schema's own parameter descriptions. Baseline 3 is appropriate when the schema does the heavy lifting.

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?

Opens with a specific verb+resource: 'Start background draft simulations and return the initial monitor status.' This clearly distinguishes the tool from siblings such as recommend_draft (synchronous single calculation) and get_draft_recommendations (results retrieval). The description makes the tool's role unambiguous without needing to inspect schemas.

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 prerequisites ('Requires a loaded draft snapshot and no active local draft monitor') and names exact alternatives with their conditions ('Use get_draft_recommendations for results, stop_draft_monitor to stop, or recommend_draft for one synchronous calculation'). This is textbook routing guidance – an agent knows precisely when to invoke this tool versus its 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?

Annotations already provide idempotentHint=true and destructiveHint=false, but the description adds valuable context: it waits up to five seconds, returns status and counters with a 'stopping' state if a batch is active, and clarifies it does not stop the ESPN companion or change saved configuration. 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?

Three concise sentences with the primary action front-loaded. Each sentence adds essential information: the action, the return state, and the scope exclusions. 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 no parameters and the presence of an output schema, the description fully covers what an agent needs: the behavior, the possible result, safety of repetition, and the next-step guidance. It is complete for a no-arg 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 tool has zero parameters, so the baseline is 4. The description correctly adds no parameter details since none exist; it focuses on behavior instead, which 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 states a specific action ('Request shutdown of the local draft monitor') with a clear resource and a time-bound behavior. It distinguishes from siblings like start_draft_monitor and get_draft_recommendations by naming the alternative for status confirmation, so an agent can easily differentiate.

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 advises using get_draft_recommendations to confirm running=false before starting another monitor, and notes that repeated calls are safe. This provides clear when-to-use and when-to-avoid guidance, plus a named alternative.

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

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

The description goes well beyond the annotations, disclosing that omitted fields reset to model defaults, that empty config is treated as all-defaults, that validation and recording occur, that unexecuted proposals and monitor results are invalidated, and that a revision conflict leaves configuration unchanged. This is rich behavioral context complementing destructiveHint=true.

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?

Every sentence earns its place: the core action, the prerequisite, the omission semantics, side effects, return behavior, and exclusions. The most important caveat is front-loaded, and there is no filler.

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

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

Given the nested config schema, output schema, and destructive annotations, the description covers the full call contract: prerequisite read, omission behavior, validation/side effects, return status, conflict behavior, and what it does not do. Nothing critical is missing.

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

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

Schema coverage is 100% and the schema already describes expected_revision and config semantics. The tool description adds value by highlighting the 'read first to preserve settings' workflow and explicitly calling out the empty-object case, which reinforces and slightly extends the schema's 'existing values are not merged' warning.

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

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

The description opens with 'Replace the saved configuration using its current configuration revision' – a specific verb, resource, and mechanism. This clearly distinguishes the tool from read-only siblings like get_manager_config and from action-execution tools.

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

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

It explicitly instructs to read get_manager_config first to preserve settings, and states what the tool does not do ('does not execute actions or start a monitor'). It does not explicitly name the action-execution siblings (e.g., execute_demo_action), but the prerequisite and exclusions provide clear context.

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