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

With no annotations, the description fully covers behavioral expectations: idempotency, no data loss, not confirm-gated, no HTTP/Socket.IO call, and the important limitation that a running job only gets cancel_requested set rather than an immediate cancelled state. It also discloses the JobNotFoundError behavior.

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

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

The description is long but every sentence earns its place; it is front-loaded with purpose and safety and uses bullets for state-specific behavior. The structure makes complex milestone-specific behavior easy to parse.

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

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

Given no annotations and no output schema, the description is remarkably complete: it covers purpose, idempotence, side effects, state transitions, async behavior, and error conditions. Nothing needed for correct invocation or expectation-setting 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 schema only defines job_id as a string with zero description coverage, so the description must carry the burden. It adds meaning by explaining how unknown job_id values are handled and referencing get_job_status for the same error behavior, though it could further clarify where valid job IDs come from.

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 resource: 'Cancel a job, or report its existing terminal state if already finished.' It distinguishes the tool's behavior across job states and separates it from siblings like get_job_status and cancel_order by describing its state-transition scope.

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

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

It clearly states this tool is for canceling jobs and describes what happens for queued vs running jobs, giving an agent a solid basis for when to invoke it. It does not explicitly enumerate alternatives or exclusions, but the intended context is unambiguous.

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

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

With no annotations provided, the description carries full behavioral disclosure and does so thoroughly: exact HTTP success behavior, literal success string, failure mode including OctoBot's swallowed internal errors, the raised exception, and the irreversibility/confirm-gating rationale. This goes far beyond a generic 'cancels an order' statement.

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 and then organized into clear route/body, success/failure, and confirmation-gating sections. It is somewhat verbose with source-code citations and internal references, but most of that detail directly supports correct invocation and behavioral expectations.

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 single parameter, no annotations, and no output schema, this description is exceptionally complete. It covers parameter construction, HTTP details, success and failure behavior, exception types, and the absence of a confirm parameter, leaving little ambiguity 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 coverage is 0%, so the description must fully explain the parameter, and it does. It clarifies that order_id is sent as the raw JSON body rather than wrapped in an object, that action is a query parameter, and that the value should come from get_orders() responses.

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

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

The opening sentence 'Cancel one order by id' names a specific verb, a specific resource (one order), and the identifying input. It is clearly distinguishable from sibling tools like cancel_job, close_position, and clear_orders_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 explains how to obtain the correct value ('Use the id field from get_orders()'s own response items'), which is key usage guidance. It does not explicitly contrast this tool with sibling alternatives or state when not to use it, but the context is strong and the invocation path is unambiguous.

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

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

With no annotations present, the description carries the full burden, and it excels: it reveals the underlying endpoint, explains the masked-placeholder credential behavior, confirms no credential passes through input/output, states it is read-only in effect, and discloses the sandboxed-hardcoded caveat. This is exemplary transparency.

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

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

The description is longer than typical but every paragraph adds value, especially given the absence of annotations and the nuanced behavior. It front-loads the purpose and then provides necessary caveats. Slight over-inclusion of source-verification detail prevents a 5 for conciseness.

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

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

Given no annotations, no output schema, and a single parameter, the description is remarkably complete: it explains the request mapping, credential handling, return behavior, and a serious caveat about sandbox mode. An agent has sufficient context to invoke it correctly and interpret 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?

Schema description coverage is 0%, so the description must compensate. It clearly explains that exchange_names is the list of exchanges to check compatibility for, and that the tool deliberately narrows its input to just this field. It doesn't specify accepted name formats or edge cases, but the core semantic is well-covered.

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: 'Check whether each named exchange's already-configured account is usable.' This clearly distinguishes it from sibling tools like update_exchange_credentials or get_exchange_details by emphasizing it validates existing stored credentials rather than accepting new ones. The scope 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 clearly implies when to use this tool: to verify compatibility of already-configured exchanges without supplying credentials. It explicitly states that credentials cannot be passed through this call and that it falls back to stored credentials. However, it does not explicitly name an alternative tool or provide a direct when-not-to-use statement, so it falls short of full 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?

With no annotations provided, the description carries the full burden and does so thoroughly. It reveals the destructive nature ('Permanently clear'), the confirm-gating logic, the exact behavior when confirmation is false (a structured refusal, not an error), the underlying POST call, and the unchanged JSON response.

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 but every sentence contributes: purpose, confirmation gate, no-op behavior, endpoint mapping, and response format. It is front-loaded and free of filler, with technical references that add verification value.

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

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

For a destructive, confirm-gated tool with no annotations and no output schema, the description is complete. It explains prerequisites, runtime behavior, side effects, and the exact return value, leaving no ambiguity for an agent deciding whether and how to 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 schema only defines `confirm` with a default of false and no description, so 0% schema coverage leaves the description to carry the meaning. The description fully explains that `confirm` must be exactly `true` and what happens otherwise, making the parameter behavior completely clear.

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 'Permanently clear OctoBot's stored orders history' – a specific verb and resource that immediately distinguishes it from sibling tools like clear_trades_history and clear_portfolio_history. The wording also conveys irreversibility, further clarifying intent.

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

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

The description clearly states the operation and the critical prerequisite: 'If `confirm` is not exactly `true`, no OctoBot call is made at all'. It doesn't explicitly contrast with alternative clear_* siblings, but the resource is unambiguous and the confirmation gate is a concrete usage condition.

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

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

With no annotations, the description carries the full burden, and it does so thoroughly. It discloses the permanent/destructive nature, the confirm-gating mechanism, the fact that a false confirm results in a structured refusal rather than an error, the exact HTTP endpoint, and the unchanged response body. This is exemplary transparency for a destructive tool.

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

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

The description is well-structured and front-loaded, with the core purpose in the first sentence. However, it contains some internal references (ADR-0003, NFR-8, module docstring, '[V]') that are likely noise for an AI agent and add little actionable value for tool selection or invocation.

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 destructive nature, lack of annotations, and lack of an output schema, the description is remarkably complete. It covers the action, the confirmation requirement, the no-op behavior when unconfirmed, the endpoint mapping, and the expected response body. An agent has everything needed to invoke it correctly and understand the consequences.

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 lone parameter confirm has 0% schema description coverage, so the description must supply all meaning. It explains that confirm must be exactly true for any OctoBot call to occur, and that otherwise a refusal is returned normally. This gives the agent far more than the schema's default value of false could.

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 begins with a specific verb and resource: 'Permanently clear OctoBot's stored historical portfolio values.' This clearly distinguishes it from sibling clear tools like clear_orders_history and clear_trades_history by narrowing the target to portfolio history only.

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

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

While the description does not explicitly name alternative tools, it provides strong contextual guidance: it is the tool for permanently clearing portfolio history, and it requires confirm to be exactly true before any call is made. The confirm-gated behavior is a clear operational condition, though no when-not-to-use or alternative comparisons are stated.

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

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

With no annotations, the description carries the full burden, and it excels: it discloses permanent destruction, confirms no side effects unless `confirm` is true, explains that the refusal path is a normal return rather than an error, maps to the exact endpoint, and specifies the response body.

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-organized and front-loaded with the core purpose, followed by confirmation semantics, endpoint mapping, and return shape. Minor internal references such as ADR-0003, NFR-8, and module docstring are not strictly actionable for an agent, so the prose is slightly less lean than it could be.

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

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

For a one-parameter destructive tool with no output schema, this description is complete: it covers the required confirmation flag, side effects, non-error refusal behavior, endpoint, and exact successful response. An agent has everything needed to invoke it correctly.

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

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

Schema coverage is 0%, so the description must explain the `confirm` parameter, and it does: `true` triggers clearing, anything else returns a structured refusal without calling OctoBot. This adds substantial meaning beyond the bare boolean 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 uses a specific verb+resource pair ('Permanently clear OctoBot's stored trades history') and leaves no doubt about the target data. It also naturally distinguishes this tool from sibling clear_* tools by naming 'trades history' specifically.

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

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

Clear invocation conditions are provided: the call is confirm-gated, and if `confirm` is not exactly `true` no OctoBot call occurs. However, it does not explicitly contrast this tool with alternatives like `clear_orders_history` or `clear_transactions_history`; the differentiation is left to the name and description.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses the destructive permanent effect, the no-op when unconfirmed, the mapping to `POST /api/clear_transactions_history`, and the exact return body. It even clarifies that the unconfirmed refusal is a normal return, not an error.

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 gating behavior, then endpoint/return details. The verification notes about re-confirming against source and 'reproduced live this session' are informative but slightly verbose for an agent selecting the tool; they could be trimmed without losing action-guiding value.

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

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

For a single-parameter tool with no annotations and no output schema, the description is complete. It covers the operation, the confirmation requirement, the exact HTTP mapping, the refusal path, and the exact success response body. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for the single `confirm` parameter. It fully explains the semantics: `confirm` must be exactly `true` for any action, otherwise no call is made and a structured refusal is returned. This is sufficient despite the schema's lack of property descriptions.

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

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

The description clearly states a specific verb ('clear') and resource ('OctoBot's stored transactions history'), and adds the critical qualifier 'permanently'. This distinguishes it from sibling clear-tools by resource and permanence without requiring schema inspection.

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 confirm-gating behavior is explicitly described: if `confirm` is not exactly `true`, no OctoBot call is made and a structured refusal is returned. This is clear usage guidance, though it does not explicitly name sibling alternatives like `clear_trades_history` or `clear_orders_history`.

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

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

With no annotations provided, the description fully carries behavioral disclosure. It details the exact HTTP route, the fact that action is a query parameter, the success response literal, the failure exception type and message, the absence of a confirm parameter, and the irreversible nature of the operation. This is far beyond the minimum.

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 a crisp purpose statement, followed by detailed sections. While the spec-correction and source-code references add length, they are informative and serve to prevent misuse. There is some redundancy in the repeated 'confirmed against' phrasing, so it is not perfectly concise, but every paragraph 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 lack of annotations, output schema, and schema-level parameter descriptions, this description is unusually complete. It covers the endpoint, parameter semantics, success behavior, failure behavior, and confirm-gating decision. An agent has everything needed to invoke the tool correctly and interpret the result.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It explains that symbol and side are the actual keys used by OctoBot, corrects the spec's position_id misconception, and lists the valid side enum values ('long'/'short'/'both'/'unknown'). It also tells the agent that values from get_positions() can be fed directly into this 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 concrete action and resource: 'Close one open position, identified by symbol and side.' It clearly names the tool's function and distinguishes it from sibling tools like get_positions (which reads) and cancel_order (which cancels orders). The resource and identifier mechanism are unmistakable.

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

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

The description provides clear context for when to use the tool: to close a position, with symbol and side as input. It even instructs that values can be passed straight through from get_positions() output. It does not explicitly name alternative tools or exclusions, but given the tool name and the absence of a sibling close-position operation, usage context is strong.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it delivers extensively: it states the tool is not confirm-gated, only starts simulations, validates all configs before creating jobs, avoids dangling queued jobs, returns immediately, always reports 'queued' in practice, and submits children sequentially through a shared lock. It also explains combined progress notification semantics and that children are never independently callable.

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 well-structured: it opens with a one-sentence summary, then adds parameter semantics, validation behavior, job structure, output shape, polling guidance, and progress notification details in labeled sections. It could be slightly tighter around internal docstring references and ADR details, but every part contributes to correct invocation.

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

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

Given the absence of both annotations and output schema, the description is remarkably complete. It specifies the output JSON shape, error conditions and exception behavior, job hierarchy, asynchronous non-blocking behavior, polling/result instructions, and progress token semantics—everything an agent needs to invoke the tool correctly and interpret its immediate result.

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

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

The schema provides almost no parameter meaning—configs is just an array of generic objects and name is loosely typed. The description compensates fully by specifying configs must be a list of length >= 2, each shaped like start_backtest's mode-specific inputs, with an optional label key that is stripped before validation, and by explicitly stating name is accepted but unused.

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

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

The first sentence, 'Compare 2+ backtest configs sequentially and return one combined job,' uses a specific verb, resource, and result. It clearly distinguishes compare_strategies from siblings like start_backtest by emphasizing the multi-config and combined-job behavior.

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 the tool is for comparing multiple backtest configs and explicitly references polling via get_job_status and retrieving results via get_job_result. It does not explicitly state 'use start_backtest for a single config,' but the '2+' constraint and repeated comparison to start_backtest make the usage context clear.

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

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

With no annotations provided, the description carries the full burden, and it is exceptionally transparent. It discloses the confirm-gating behavior, the underlying HTTP route, the non-informative 302 response, the post-hoc re-check via is_selected, the profile_type verification gap, the conditions under which errors are raised, and the fact that non-5xx responses are only a reasonably strong signal rather than definitive proof.

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 overlong and repetitive. It includes extensive source-code archaeology, multiple 'spec correction' sections, repeated phrases like 'confirmed against source,' and lengthy tangential explanations that go far beyond what is needed for an agent to call the tool. The front-loaded purpose is good, but almost every sentence after the first few could be substantially condensed.

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

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

Despite its excessive length, the description is highly complete: it covers the tool's exact behavior, confirmation requirements, HTTP mapping, response limitations, error classification, verification strategy, known gaps, and success output shape. An agent has enough context to call the tool correctly and to understand the limits of what the result means.

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

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

Schema description coverage is 0%, so the description must compensate. It explains that profile_id is used in the underlying route and re-check, and it explains that confirm must be exactly true and that anything else produces a structured refusal. It does not provide a full formal parameter reference, but it gives enough operational meaning for both 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 opening sentence states exactly what the tool does: 'Relabel a profile as OctoBot's internal ProfileType.LIVE and select it.' It is a specific verb+resource statement that clearly differentiates this tool from siblings like select_profile, and the bold warning that it does NOT enable real-money trading removes a likely source of confusion.

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

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

The description clearly explains when confirm is required, what happens if confirm is not exactly true, and explicitly warns that no server tool can toggle real-vs-simulated trading on a default OctoBot instance. It could be slightly stronger by explicitly naming select_profile as the alternative when only selection is needed, but the guidance is otherwise clear.

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

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

With no annotations, the description carries the full burden, and it excels: it discloses side effects ('creates new state, never destroys anything or touches credentials/live trading'), non-confirm-gating behavior, error semantics (raises ProfileImportFailedError), and known upstream issues (import_url broken, import_file never returns JSON). This is far more transparency than typical tool descriptions.

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 every sentence earns its place given the four-mode complexity. It is front-loaded with the core purpose, structured with bullets for each mode, and includes only high-value caveats such as known spec corrections and upstream breakage. No redundant listing of schema types; all prose adds operational meaning.

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 8-parameter tool with no annotations, no output schema, and no per-parameter descriptions, this description is complete. It covers per-mode required arguments, optional arguments, output shape, error behavior, and safety profile. An agent has everything needed to select the correct mode and construct a valid call, including awareness of the broken import_url mode.

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

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

Schema description coverage is 0%, so the description must compensate, and it does thoroughly. It maps every parameter to its relevant mode, defines file_base64 as raw bytes base64-encoded, clarifies that description defaults to empty string, and states that irrelevant arguments are ignored. Each of the 8 parameters is effectively explained through the mode-based requirements.

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

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

States a specific verb and resource: 'Create a new profile, one of 4 ways, discriminated by mode.' The four modes are enumerated, making the tool's scope unmistakable and distinguishing it from sibling profile tools like update_profile, delete_profile, and list_profiles. The resource is clearly a profile and the action is creation.

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 clear context on when to use the tool: it creates a new profile and is not confirm-gated, emphasizing it never destroys state or touches credentials/live trading. It also explains that only mode-relevant arguments need to be supplied. However, it does not explicitly name sibling alternatives or state when to choose this over another profile-related tool, so it falls short of 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?

With no annotations provided, the description carries the full behavioral burden and does so excellently. It discloses the permanent destructive nature, the confirm-gated behavior, the structured refusal when confirm is not true, the exact HTTP mapping, the JSON body format, the success response, and the error wrapper with a verbatim example.

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 essential purpose and gating behavior, and it is well-structured across intent, behavior, success output, and errors. It is somewhat verbose with provenance details like 'reversed from this addendum's original not-gated draft' that are not needed for tool invocation, but this is a minor deduction given the complexity of the destructive behavior.

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

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

Given no output schema and no annotations, the description is remarkably complete: it covers preconditions, confirmation semantics, endpoint mechanics, success return shape, and error behavior. An agent could safely understand and invoke this tool correctly without 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 description coverage is 0%, so the description must compensate, and it does thoroughly. It explains that confirm must be exactly true to execute and otherwise returns a structured refusal, and that file is passed raw as the JSON body rather than inside a wrapping object.

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: 'Permanently delete a historical data file.' This is immediately unambiguous and clearly distinguishes the tool from history-clearing and order-cancellation siblings by naming the risk profile it shares with clear_*_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 provides a clear risk comparison with cancel_order/close_position and clear_*_history, explaining when this destructive action is warranted versus the instantly-correctable operations. It does not give an explicit 'use this when...' rule, but the context and exclusions are reasonably clear.

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

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

With no annotations provided, the description fully carries the behavioral burden. It discloses irreversibility, the confirm gate, that no OctoBot call is made without confirmation, two failure modes, local rejection of unknown IDs, the OctoBot success-body bug, the extra post-deletion safety check, and name capture before deletion. This is exceptionally transparent.

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

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

Though lengthy, the description is well-structured and front-loaded with the core action. Each paragraph addresses a distinct concern: confirmation behavior, API mapping, failure modes, safety verification, and return shape. The detail about source-code confirmation and the copy-paste bug is justified given the tool's destructive and surprising behavior.

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

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

Given no output schema and no annotations, the description is remarkably complete. It covers exact invocation conditions, error modes, success output shape, and the fallback safety check. There are no significant gaps that would prevent an agent from calling this 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?

Schema description coverage is 0%, but the description compensates fully. It explains that confirm must be exactly true, describes what happens if false, defines profile_id semantics (active profile, blocked removal, unrecognized ID), and even documents the JSON body shape sent to the API.

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 'Permanently delete a profile', which is a specific verb+resource statement. It goes on to specify the exact endpoint and body mapping, and is clearly distinct from sibling tools like create_profile, update_profile, and select_profile.

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

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

The description clearly establishes when this tool applies: confirm-gated, irreversible profile deletion, with a structured refusal if confirm is not exactly true. It does not explicitly enumerate alternatives or when-not-to-use, but the uniqueness of the destructive operation makes the usage context unambiguous.

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

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

With no annotations, the description carries the full burden, and it delivers: base64 encoding, bypass of request_json, Content-Disposition filename parsing, redirect-on-failure behavior, and the explicit OctoBotMalformedResponseError fallback. It also discloses read-only, non-confirm-gated behavior via ADR-0003.

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 longer than necessary for a zero-parameter tool, but it is front-loaded with the core purpose and each paragraph addresses a meaningful concern (wire format, filename handling, failure semantics, output shape). Some meta-references to module docstrings and source verification could be trimmed without loss.

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

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

Given no output schema and no annotations, the description fully specifies the return format, error behavior, and read-only/gating status. An agent has everything needed to invoke and interpret 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, so the baseline is 4 and there is nothing for the description to add about arguments. It instead documents the output contract, which is the relevant semantic content for this 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?

Opens with a clear verb+resource statement: 'Export OctoBot's full logs as a zip archive, base64-encoded.' The format and scope are explicit, but it never contrasts the tool with sibling get_logs, relying on the name and first sentence for differentiation.

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

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

The description implies usage—call this when a full logs export is needed—and draws a useful analogy to export_profile. It does not, however, state when to prefer this over get_logs or mention any exclusions/prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure and does so thoroughly. It reveals that the response is raw bytes, that the body is base64-encoded, that filename is derived from Content-Disposition rather than fabricated, that malformed headers raise OctoBotMalformedResponseError, and that unknown profile_id yields an HTTP 500 with NoProfileError. This is exemplary transparency.

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

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

The definition is front-loaded with a clear purpose and organized into focused paragraphs. It is verbose, and some implementation archaeology such as 'moved there in milestone 13' and RFC references is more detail than an agent needs to invoke the tool. Still, the structure is logical and the length mostly serves genuine behavioral transparency rather than 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?

Despite the absence of annotations and output schema, the description defines the exact output shape, error behavior, read-only nature, confirmation-gating status, and endpoint mapping. An agent has everything needed to invoke the tool correctly and interpret its result.

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

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

The schema provides only the parameter name with no description, so schema coverage is 0%. The description compensates by confirming the exact query-param name (profile_id, not id) and by documenting the failure mode for an unknown profile_id. It does not elaborate on where to obtain a valid profile_id or its format, but for a single self-explanatory parameter this is sufficient added meaning.

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

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

The opening sentence states a specific verb and resource: 'Export a profile as a zip archive, base64-encoded.' This unambiguously distinguishes it from sibling profile tools like get_profile, which retrieves profile details rather than producing a downloadable archive. The endpoint mapping reinforces the purpose without introducing ambiguity.

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

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

The description clearly implies the tool is for exporting a profile archive, and it notes the operation is read-only and not confirm-gated. However, it does not explicitly say when to prefer this over alternatives such as get_profile or list_profiles, nor does it state any exclusions or prerequisites. Usage context is present but only by implication.

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

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

With no annotations, the description carries the full burden and does it well: it explicitly states the operation is read-only, not confirm-gated, and returns OctoBot's own JSON body unchanged. It also adds provenance by referencing the OctoBot source file for confirmation.

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 primary purpose. The additional sentences each add useful behavioral or technical context without unnecessary 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 simple one-parameter tool, the description covers the operation, endpoint mapping, safety behavior, confirmation requirement, and return behavior. The main missing piece is validation of the exchange parameter value, but overall the context is largely sufficient without an output schema.

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

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

The description adds some meaning beyond the bare schema by clarifying that the 'exchange' parameter selects the single exchange whose currency list is returned. However, it does not specify accepted exchange identifiers, formats, or how to obtain them, which is a gap given 0% schema description 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 states a specific verb ('List'), a clear resource ('every currency OctoBot knows about'), and a scope ('for one exchange'). It also maps to a concrete endpoint, which makes the tool's purpose unambiguous and distinguishes it from exchange-wide or symbol-focused siblings.

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

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

The description implies usage when an agent needs all currencies for a particular exchange, and the 'for one exchange' wording provides some context. However, it does not explicitly name alternatives or state when not to use this tool, especially relative to the similar-looking sibling get_currency_list.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly states the operation is read-only, not confirm-gated, maps to a GET endpoint, and returns OctoBot's JSON body unchanged. This goes well beyond a generic tool description.

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

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

The description is extremely concise and well-structured: one purpose sentence, one endpoint/source sentence, and one behavioral/return sentence. Every sentence adds distinct value with no repetition or filler.

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

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

For a simple single-parameter read-only tool, the description covers the main operational aspects: purpose, endpoint, read-only safety, and response handling. It is slightly incomplete in not detailing the exchange parameter's accepted values or the exact JSON output structure, but the core usage is adequately covered.

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 has only one parameter, 'exchange', with 0% description coverage. The description merely implies the parameter's role with 'for one exchange' but does not specify valid values, format, or how exchanges are identified in OctoBot. This is insufficient compensation for the missing schema documentation.

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: 'List every trading symbol/pair OctoBot knows about for one exchange.' This clearly distinguishes the tool from sibling names like get_currency_list or get_all_currencies by focusing on symbol/pair data scoped to a single exchange.

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 usage context is implied rather than explicit: use it when you need all trading symbols/pairs for one exchange. However, it does not mention alternatives, exclusions, or how it differs from related listing tools such as get_all_currencies or get_exchange_details.

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

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

With no annotations provided, the description carries the full behavioral burden, and it delivers: it states read-only behavior, absence of confirm gating, no dedicated exception class, direct passthrough of OctoBot's sorted JSON array, and the exact output shape. This goes well beyond a minimal description and gives the agent clear expectations for side effects and failure modes.

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 and then provides endpoint mapping, output format, and behavioral notes. The paragraph explaining why there is no sibling symbols tool is somewhat tangential to actually invoking this tool, but it is still useful for tool-set navigation. It is longer than strictly necessary but every section contributes context.

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

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

For a one-parameter, read-only tool with no output schema and no annotations, the description covers the essential facts: endpoint, request parameter, output structure with an example, read-only nature, exception behavior, and relationship to existing tools. There are no obvious gaps that would prevent an agent from making a correct call.

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

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

Schema description coverage is 0%, so the description must compensate for the undocumented `exchange` parameter. It only shows `exchange` appearing in the endpoint query string and says 'for one exchange,' but it does not explain valid exchange names, identifier vs. display name, or any expected format. Some meaning is added beyond the bare schema, but it is not enough for reliable parameter construction.

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: 'List the time frames OctoBot's data collector supports for one exchange.' It also maps to a concrete endpoint, which removes ambiguity. The purpose is further distinguished from sibling tools by explaining why a similar symbols-listing tool does not exist, so the agent can place this tool in the overall collection.

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 operational context: it is read-only, not confirm-gated, and returns time frames for one exchange. It does not explicitly state 'use this before start_data_collection' or list alternative tools for the same purpose, but it does explain why no sibling `get_available_symbols_for_collection` exists and references `get_all_symbols` as a conventional analog. This is sufficient context though not a full when-to-use/when-not-to-use guide.

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

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

With no annotations, the description fully carries the burden and does so exceptionally well. It discloses the read-only nature, the no-op exchange parameter, the lack of request arguments, that it is not confirm-gated, and that it returns the server's JSON unchanged. It also grounds the claim in the actual route and session verification.

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?

Though longer than average, every sentence earns its place. The core purpose is front-loaded, and the rest adds critical behavioral and compatibility context that prevents misuse. There is no fluff 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?

For a simple read-only listing tool with one optional parameter and no output schema, the description is complete. It covers purpose, endpoint, parameter behavior, safety profile, and return behavior. 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?

Schema coverage is 0%, and the description fully compensates. It explains that exchange is accepted only for forward-compatibility, that the deployed route takes no arguments, and that the parameter has no effect on the result. This is exactly the meaning an agent needs beyond the raw schema.

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

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

The description clearly states the tool lists OctoBot's globally configured trading currencies/symbols and maps to a specific endpoint. It is clear about the resource and scope, but it does not explicitly differentiate from similar siblings like get_all_currencies or get_all_symbols.

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: the tool always returns the same global list and the exchange parameter is a no-op filter on the current OctoBot route. This tells the agent when the tool is appropriate, though it does not explicitly name alternative tools for filtered or exchange-specific lists.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses that the operation is read-only, not confirm-gated, returns exactly one exchange, never enumerates all exchanges, and returns OctoBot's JSON body unchanged. This is far beyond minimal and gives the agent accurate behavioral expectations.

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 a clear one-sentence summary, then proceeds with important caveats. It is somewhat long, but nearly every sentence contributes necessary behavioral or usage nuance. Minor extras like the source file reference and 'NFR-8' are acceptable context rather than padding.

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

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

For a tool with one optional parameter and no output schema, this description is complete. It covers the endpoint mapping, parameter semantics, single-result guarantee, read-only nature, confirmation requirements, and return behavior. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 0%, so the description must compensate, and it does. It explains that exchange_name, when provided, selects the matching exchange, and when omitted, the tool returns OctoBot's 'first exchange.' This adds real meaning to the otherwise bare schema definition.

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

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

The first sentence uses a specific verb and resource: 'Fetch ONE exchange's name and internal id.' It clearly scopes the tool to a single exchange and distinguishes it from any list-style tool by emphasizing 'ONE' and later 'It does NOT enumerate every exchange.'

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 about when the tool is appropriate, including the optional exchange_name behavior and the fallback to 'the first exchange.' It also provides a strong exclusion: do not call this tool expecting a full exchange list. However, it does not name a specific alternative tool to use when a full list is needed.

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

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

With no annotations, the description carries the full behavioral burden. It explicitly discloses that the operation is read-only, is not confirm-gated, returns OctoBot's JSON body unchanged, and that currency defaults to USDT server-side. This is strong transparency for a simple fetch 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 front-loaded with the core purpose and stays reasonably compact. The source-confirmation detail is useful but makes the second sentence dense; still, every sentence contributes relevant information.

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

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

For a read-only GET-like tool with five optional parameters and no output schema, the description covers endpoint, parameter optionality, default behavior, and response identity. It could be more complete about return value structure and parameter formats, but it is sufficient for correct invocation in most cases.

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

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

Schema description coverage is 0%, so the description must compensate. It names all five query parameters and states they are optional filters, and it adds the useful currency default behavior. However, it does not explain timestamp formats, time_frame units, or valid exchange values, leaving meaningful semantic gaps.

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

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

The description starts with a specific verb and resource: 'Fetch historical portfolio value samples, optionally filtered.' It also names the exact endpoint, making the tool's scope unambiguous and distinct from sibling tools like get_pnl_history or get_orders.

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 useful invocation context: all query parameters are optional, and the call is read-only. However, it does not explicitly say when to prefer this tool over sibling tools or when not to use it, leaving some selection reasoning to the agent.

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

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

With no annotations present, the description carries full responsibility and delivers thoroughly: error cases, no-partial-results guarantee, passthrough semantics, exact output structure, field types (strings vs numbers), and the fact that the tool does not validate or hardcode field names. This is exemplary behavioral disclosure.

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

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

The description is front-loaded with the core purpose and precondition, and the sections are logically organized. However, it is overlong, with internal references (milestone, NFR-8, INV-3, docs/tasklist) and a large live JSON example plus lengthy meta-commentary that could be trimmed without sacrificing essential guidance.

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

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

Given there is no output schema or annotations, the description is exceptionally complete: it covers prerequisites, all error behavior, output shapes for both job kinds, passthrough guarantees, and real observed field types. An agent has essentially everything needed to call the tool and interpret its result.

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 has 0% description coverage for the single job_id parameter. The description mentions job_id only in the error context ('Raises JobNotFoundError for an unknown job_id'), adding limited meaning beyond the schema. However, the tool name and the rest of the description make the parameter's purpose unambiguous, so minimal compensation is acceptable.

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: 'Fetch a completed backtest job's final report.' It also clarifies the two job kinds (backtest and compare_strategies) and their distinct output shapes, making it easy to differentiate from sibling tools like get_job_status or list_jobs.

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

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

The description clearly states when to use the tool: requires state == 'completed', otherwise raises JobNotCompletedError and never returns partial results. It also explains the two output variants. It doesn't explicitly name alternatives like get_job_status for checking state, but the precondition itself gives strong contextual guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it declares read-only, not confirm-gated, no route (in-memory only), and details error behavior for unknown job_id, including the server-restart caveat. This is exemplary transparency for an MCP 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 main action is front-loaded and each major behavior gets a sentence. The parenthetical doc-spec reference and ADR mention add traceability but are somewhat redundant/verbose, so it isn't maximally concise.

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

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

For a single-parameter, side-effect-free lookup, the description covers purpose, storage scope, read-only safety, and error semantics. The main missing piece is the success return value shape, which matters because no output schema exists, but the tool is simple enough that the gap is minor.

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 for job_id is 0%, so the description must compensate. It adds that job_id selects one job and that an unknown job_id raises JobNotFoundError, which is useful. But it doesn't explain the expected format of job_id or how to obtain valid ids, leaving a partial gap.

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

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

Description opens with a specific verb+resource: 'Fetch one job's current status from the in-memory job store.' It clearly states the tool is a single-job lookup, not a list or result fetch, and distinguishes itself by explicitly noting it maps to no OctoBot route. This separates it from siblings like list_jobs and get_job_result.

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: this is a read-only, non-confirm-gated, in-memory-only lookup for one job. However, it never explicitly names alternatives or states when not to use it, so an agent must infer the boundary against siblings such as list_jobs and get_job_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?

With no annotations provided, the description carries full behavioral burden and excels: it discloses 'Never makes an HTTP call to OctoBot and never raises,' states the response is 'static, instant... not a failure,' and even notes that 'ctx is accepted only for interface consistency... never read.' This is rich, honest behavioral disclosure.

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

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

Three sentences, each earning its place. The first sentence front-loads the stub status and root cause, the second explains behavior precisely, and the third gives the actionable alternative. No filler, no 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?

For a zero-parameter, no-output-schema stub, the description covers everything an agent needs: what happens when called, what does not happen, and which sibling tool to use instead. The ADR-0006 reference adds provenance. 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?

There are no schema parameters (0 params, 100% schema coverage), so the baseline is 4. The description adds meaningful extra context by explaining the otherwise invisible 'ctx' parameter: it is accepted only for interface consistency and is never read. This goes beyond the empty schema.

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

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

The description explicitly identifies this as a 'Tier C stub' that exists because 'structured/filterable log listing has no JSON API in OctoBot.' It clearly states what the tool does—returns a static response explaining the gap—rather than pretending to fetch logs. This distinguishes it from sibling tools like export_logs.

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 direct routing guidance: 'Use export_logs() instead to retrieve OctoBot's full log history as a downloadable zip archive.' This names the alternative and the condition selecting it, leaving no ambiguity about when this stub is appropriate.

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

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

With no annotations provided, the description carries the full behavioral burden and largely meets it: it declares 'Read-only, not confirm-gated' and states the passthrough return behavior ('Returns OctoBot's own JSON body unchanged (NFR-8)'). Minor gaps remain, such as result ordering or volume limits, but for a zero-parameter read tool this is strong disclosure.

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

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

Three short sentences with the core purpose front-loaded before the endpoint mapping and behavioral notes. Every sentence carries distinct information — scope, HTTP mapping, safety, and return behavior — with no redundancy.

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

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

For a parameterless list tool with no output schema and no annotations, the description covers scope ('every order... open and historical'), the underlying endpoint, side effects (read-only), the confirmation model, and the return contract. Nothing an agent needs to know before calling 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 takes zero parameters and schema description coverage is trivially 100%, so there are no parameter semantics the description must document. Per the zero-parameter baseline, the description's silence on parameters is acceptable; nothing is left unexplained.

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

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

The description opens with a specific verb and resource: 'List every order OctoBot currently knows about,' and explicitly scopes coverage to 'open and historical.' This distinguishes it from sibling tools like get_trades and get_positions by naming the resource, and from clear_orders_history and cancel_order by framing the operation as a read-only listing.

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

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

No explicit alternatives or when-to-use/when-not-to-use guidance is given. The resource scope and 'Read-only, not confirm-gated' phrasing imply this is the safe read path for orders, but the description never points to siblings like clear_orders_history or cancel_order for mutating needs — the agent must infer that separation itself.

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

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

With no annotations present, the description carries the full burden and handles it well: it explicitly states 'Read-only, not confirm-gated' and that OctoBot's JSON body is returned unchanged. This tells the agent the call is safe, requires no confirmation, and preserves the upstream response.

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 action and then gives endpoint mapping, filter guidance, and behavioral notes. The source-verification and 'NFR-8' details add provenance but are slightly internal/jargon-heavy, preventing a perfect score.

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

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

For a simple read-only filtered endpoint, it covers the endpoint, optional parameters, safety profile, and response handling. It does not describe the JSON body's contents, and there is no output schema to fill that gap, so it is not fully complete.

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

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

Schema description coverage is 0%, so the description must compensate, but it only lists the five parameter names and calls them optional filters. It does not define the meaning or accepted format of 'since' or 'scale', nor clarify the values for exchange, symbol, and quote beyond their self-evident names.

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

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

The opening sentence uses a specific verb and resource: 'Fetch realized PnL history, optionally filtered.' This clearly states what the tool does, but it does not explicitly contrast it with sibling tools like get_trades or get_historical_portfolio_value, so it stops short of full sibling differentiation.

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

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

It provides clear operational context: all five query parameters are optional filters and users should omit any they don't want to filter by. It does not name alternative tools or give when-not-to-use conditions, so it doesn't reach the top of the scale.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden. It explicitly states 'Read-only, not confirm-gated' and that it returns OctoBot's own JSON body unchanged (NFR-8), providing important safety and response-shape context beyond a mere endpoint listing.

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 filler. The main purpose is front-loaded, followed by endpoint mapping and behavioral guarantees, each sentence adding distinct value.

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

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

For a parameterless, read-only list endpoint, the description covers all essential aspects: what it lists, the HTTP mapping, safety profile, and response behavior. Nothing an agent needs to call 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 input schema has zero parameters and schema description coverage is 100%, so there are no parameter semantics for the description to add. Per the baseline for parameterless tools, a 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?

The description clearly states a specific verb ('List') and resource ('every trading position OctoBot currently knows about'), making the tool's purpose unambiguous. It also distinguishes itself from sibling mutation tools like close_position by explicitly labeling itself as read-only.

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

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

The description provides clear context: it is a read-only, non-confirm-gated way to fetch all positions, which implies choosing it over mutation or confirmation-gated tools. It does not explicitly name alternatives or state when not to use it, but for a simple list endpoint the usage context is clear.

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

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

With no annotations, the description carries the full behavioral burden. It discloses that the tool reuses list_profiles' scrape and filters rather than scraping again, explains the default profile behavior, and precisely distinguishes two error types: ProfileNotFoundError for an unmatched ID versus ProfileScrapeContractBrokenError for a broken scrape. This is strong behavioral context.

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, front-loaded with the core purpose, and every sentence serves a purpose: the first states the operation, the second explains the implementation, and the third clarifies error semantics. 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?

For a one-parameter fetch tool with no output schema, the description is nearly complete: it covers default behavior, error cases, and how it relates to list_profiles. It does not describe the shape of the returned profile details, but this is not critical 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?

Schema description coverage is 0%, so the description must provide meaning for the profile_id parameter. It does: profile_id is optional, absence means use the currently selected profile, and providing an unmatched ID raises ProfileNotFoundError. This adds real semantics beyond the raw schema, though it does not elaborate on the ID's format.

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 operation ('Fetch one profile's details') on a clear resource (profile), and differentiates itself from list_profiles by noting it uses the same scrape but filters the result. The default-to-current-profile behavior further disambiguates it from sibling profile 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 makes clear this tool is for retrieving a single profile, optionally by ID, and defaults to the currently selected profile. It references list_profiles, implying list_profiles is the alternative for getting all profiles, though it does not explicitly state 'use list_profiles instead.'

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it declares read-only/non-confirm-gated behavior, documents the exact response shape and semantics, discloses the live-confirmed HTTP 500 error for unknown tentacle names and the error-body mismatch, and even explains the internal error-extraction handling.

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, then structured into endpoint mapping, return shape, and error behavior. It is longer than typical, and a few internal implementation details (module docstring reference, NFR-8 label, Content-Type header nuance) are beyond what an agent strictly needs, but the density is still justified by the tool's complexity.

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

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

For a single-parameter read tool with no annotations and no output schema, the description is remarkably complete: it covers the parameter format, response fields and their meaning, the read-only safety profile, and the failure mode without requiring the agent to make assumptions.

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 offers no description for the single required parameter, but the description fully compensates by stating that tentacle is the tentacle's class name and providing a concrete example ('DailyTradingMode'). This is exactly the semantic information an agent needs to construct a valid call.

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: 'Fetch one tentacle's current configuration, schema, and display metadata.' This clearly distinguishes it from the sibling list_tentacles (which lists tentacles) and update_tentacle_config (which modifies configuration), and the endpoint mapping reinforces the exact operation.

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

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

The description makes the read-only purpose and relationship to update_tentacle_config clear, implying when to use this tool versus the update sibling. However, it does not explicitly state exclusions such as 'use list_tentacles to enumerate all tentacles' or 'use update_tentacle_config when modification is needed.'

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 absent, so the description fully carries the behavioral disclosure burden. It explicitly states the operation is read-only, maps to GET /api/trades, and returns OctoBot's own JSON body unchanged, which directly informs an agent about side effects and response handling.

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 core purpose, followed by the endpoint mapping and behavioral notes. Every sentence adds meaningful information without redundancy or filler.

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

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

For a zero-parameter, read-only list operation without an output schema, the description is complete: it states the resource, the HTTP method, the read-only nature, and the exact response behavior. 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 the input schema is empty, so the description is not required to explain parameter behavior. The baseline for zero-parameter tools is 4, and the description appropriately avoids adding irrelevant parameter 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 opens with a specific verb and resource: "List OctoBot's trade history." This clearly distinguishes it from sibling tools like get_orders, get_positions, and clear_trades_history, and the explicit endpoint mapping reinforces the exact operation.

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 this tool is appropriate by stating it is read-only and not confirm-gated, meaning no confirmation is needed before invoking it. It does not explicitly name alternatives or state when not to use it, but the read-only framing provides sufficient usage guidance for this simple no-parameter tool.

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

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

With no annotations, the description carries full behavioral burden and does so impressively. It discloses the non-confirm-gated behavior, the create-nothing-destroy-nothing state model, the OctoBot silent-rejection limitation (HTTP 200 even on failure), and the before/after list_data_files() verification strategy.

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 nearly every sentence carries essential caveats or implementation context that cannot be inferred from the schema. It is front-loaded with the core purpose, then systematically covers behavior, output, and errors. Minor redundancy around the create_profile analogy could be trimmed.

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

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

For a tool with no output schema and no annotations, the description covers everything an agent needs: the exact invocation pattern, the multipart format, the verification mechanism, the output contract, and the error conditions. It even references the relevant sibling verification tool (list_data_files).

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

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

Schema description coverage is 0%, so the description must clarify the two parameters. It explains that file_base64 should be valid base64 and is base64-decoded into a multipart 'file' field, and it shows filename in the output shape. This adds real meaning beyond the raw schema, though a direct per-parameter definition would be slightly stronger.

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

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

The first sentence states a specific verb ('Upload'), a specific resource ('existing OctoBot-format historical data file'), and a clear exclusion ('without collecting it via an exchange'). It unambiguously distinguishes this import operation from data-collection workflows, so an agent can identify the tool 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 clarifies when the tool applies: when an OctoBot-format data file already exists and should not be collected via an exchange. It does not explicitly name sibling alternatives like start_data_collection, but the 'without collecting it via an exchange' framing plus the route mapping provides enough 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?

With no annotations provided, the description fully carries behavioral disclosure. It explicitly states idempotency, read-only behavior, lack of confirmation gating, the scraping mechanism, fail-loud assumptions, and the distinction between an empty list and a scrape contract break. This is thorough and actionable.

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 adds necessary implementation and behavioral details in a compact, structured format. The output schema is inline and each sentence provides actionable information without redundancy.

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

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

For a zero-parameter read-only tool, the description is complete: it specifies the resource, output shape, error semantics, and relationship to delete_data_file. The agent has everything needed to understand when to call it and how to interpret the result.

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 input parameters, so the baseline of 4 applies. The description compensates further by documenting the full output structure and the meaning of the `file` field, which helps the agent interpret the result even though no output schema 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 states a specific verb and resource: list every historical data file present on the OctoBot instance. It clearly differentiates the tool from siblings like delete_data_file, import_data_file, and start_data_collection by emphasizing enumeration of existing files.

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

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

The description implies when to use the tool by stating that the returned `file` value is the authoritative identifier to pass to `delete_data_file`, which routes an agent toward file-management workflows. It also notes the tool is not confirm-gated. However, it does not explicitly contrast with other listing or data-collection tools.

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

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

With no annotations provided, the description carries the full burden, and it is exceptional: it discloses read-only/idempotent behavior, fail-loud assumptions, and precisely when EvaluatorScrapeContractBrokenError is raised versus when it is not. It even documents a confirmed live edge case to prevent false alarms.

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 longer than average but every section earns its place: core purpose is front-loaded, then usage relationship, output format, and error behavior. It is slightly dense with ADR references and governance details, but these are substantive context rather than 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?

Despite having no output schema, the description fully specifies the return shape, field types, enum values, and the meaning of the name field. It also covers error semantics and lists the exact failure conditions, making the tool self-contained for an agent to invoke correctly.

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

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

The tool has zero parameters, so the schema already fully covers parameter semantics and there is nothing for the description to add. The description instead clarifies the output fields and their meanings, which is the relevant semantic content for this no-argument 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 opening line states a specific verb ('List'), a clear resource ('every evaluator OctoBot knows about'), and the key distinguishing details: activation state and category. It also explicitly names sibling update_evaluator_config and explains how this tool closes its read gap, so an agent can tell them apart.

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 usage context: this is the companion-read for update_evaluator_config, which is unusable without knowing an evaluator's exact class name and current state. It also states that the tool is idempotent, read-only, and not confirm-gated, giving clear behavioral guidance for when it is safe to call.

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

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

With no annotations provided, the description carries the full disclosure burden and does so well: it states the operation is read-only, not confirm-gated, purely in-memory, and not backed by an OctoBot route. It also discloses the return entry shape by referencing get_job_status minus sub_jobs.

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 action and constraints, then delivers filters, safety semantics, and return-shape information in a compact structure. Every sentence earns its place and there is 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?

For a simple read-only list tool with two optional parameters and no output schema, the description is complete: it covers scope, filtering values, optionality, side-effect behavior, and the return shape via a pointer to get_job_status. Nothing essential is missing for an agent to call it correctly.

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

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

Schema description coverage is 0%, but the description fully compensates by naming both parameters, listing their allowed values (state: queued/running/completed/failed/cancelled; kind: backtest/compare_strategies), and clarifying that each is optional and can be omitted independently. This adds meaning the bare schema lacks.

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

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

The opening sentence names a specific action and resource: 'List jobs known to the in-memory job store, optionally filtered.' It also distinguishes itself from route-backed siblings by stating it maps to no OctoBot route and is purely an in-memory listing, so an agent can tell it apart from tools like get_job_status.

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

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

The description clearly explains filtering behavior: state and kind are optional, and omitting either or both disables that filter. It does not explicitly say when to prefer get_job_status over this tool, though mentioning get_job_status's shape implies the relationship; explicit alternative routing would make it 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?

With no annotations, the description carries the full burden and does this well: it explicitly discloses idempotence, read-only behavior, absence of confirmation gating, the scraping approach, and the non-null `warning` semantics. It also explains why `profile_type: "UNKNOWN"` is a legitimate reported state rather than a failure, which is valuable behavioral context.

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 first, then behavioral traits, then the warning edge case. It avoids redundancy and keeps the most important information front-loaded.

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

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

For a zero-parameter read-only tool, the description covers purpose, safety, edge-case behavior, and the source endpoint. The main gap is that the full return shape and the specific fail-loud assumptions are only referenced via the module docstring rather than included here, so an agent cannot fully self-serve from the description alone.

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 schema already completely covers the input side. The description goes beyond the schema by explaining the output-related `warning` and `profile_type` semantics, which is more than the baseline requires.

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

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

States a specific verb and resource: 'List every profile OctoBot knows about', which clearly distinguishes it from single-profile operations like get_profile. It also adds that the selected profile is included, giving extra useful scope beyond the name alone.

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 conveys what the tool does and that it is read-only, but it does not explicitly state when to use this tool versus get_profile, select_profile, or other profile-related siblings. Usage context is implied rather than directly spelled out.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses that the tool never makes an HTTP call, never raises, returns an instant static response, and accepts ctx only for interface consistency but never reads it. This is exemplary transparency for a stub.

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 tightly structured: it front-loads the stub nature, then the behavioral guarantees, then the routing alternative. Every sentence earns its place, and the ADR reference adds useful context without bloat.

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 and no output schema, the description covers everything an agent needs: why the tool exists, what it returns conceptually, that it is not a failure, and which sibling to use for real functionality. 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?

The input schema is empty and description coverage is complete. The description goes further by clarifying that the optional ctx parameter is accepted but ignored, which prevents an agent from assuming it has functional meaning. For a zero-parameter tool, this is more than the schema alone provides.

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

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

The description clearly states this is a stub for tentacle enumeration that returns a static explanation rather than an actual list, and it explicitly names the underlying gap ('no JSON API in OctoBot'). It also distinguishes itself from get_tentacle_config, making the tool's purpose and non-purpose 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 gives explicit guidance on when to use this tool versus the alternative: use get_tentacle_config(tentacle) if you already know the tentacle's class name. This directly tells the agent how to route between sibling tools and leaves no ambiguity.

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

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

With no annotations provided, the description carries the full behavioral disclosure burden and does so thoroughly: it reveals the exact HTTP method and request body, the literal success payload, the exception type and message, the expected failure case, and the non-destructive nature of the operation. This is far more transparency than an agent would get from the empty schema alone.

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 action and then logically organized into request shape, success, failure, and confirmation status. It is somewhat wordy with implementation archaeology like 'confirmed against source', 'NFR-8', and 'ADR-0003', but those details still contribute behavioral clarity in the absence of annotations.

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 no output schema and no annotations, this description is effectively complete: it covers the request shape, the exact success response, the failure exception, and the common false-alarm scenario of a simulated-only instance. An agent has everything needed to call it correctly and interpret the result.

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

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

The input schema has zero parameters, and the description still goes beyond the baseline by explicitly stating that the POST has no request body and that no confirm parameter exists. This removes any doubt that the tool must be invoked with an empty argument object.

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

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

The opening sentence names a specific action ('trigger an immediate refresh') and a precise resource ('every enabled real (non-simulated) trader's portfolio'), clearly distinguishing it from read-only or history siblings like get_positions and get_historical_portfolio_value. The endpoint mapping reinforces the operation without ambiguity.

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

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

The description clearly conveys the tool's scope and explicitly flags that a failure on simulated-only instances is expected, which provides useful context. However, it never states when to prefer this tool over alternatives such as get_historical_portfolio_value or get_positions, so the when-to-use guidance remains implied rather than explicit.

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

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

With no annotations provided, the description carries the full burden and fully discharges it: it discloses abrupt kill-and-re-exec, lack of graceful shutdown, the unverified downtime window, exchange-side order reconciliation, refusal behavior, and residual race risk. This goes well beyond a generic 'restarts the bot' statement.

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 and is well structured with a numbered check order. It is verbose, and some internal references (ADR-0010, open question #14, A3) are tangential for tool invocation, but the length is largely justified by the risk of an abrupt restart.

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

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

Despite no output schema, it documents the success response, error path, refusal return, and recommended follow-up (wait_for_octobot_ready, then re-confirm profile). It also covers edge cases such as inconclusive profile scrapes and the job-start race, making the definition complete 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?

Schema coverage is 0%, but the description fully compensates by explaining that confirm is a strict boolean gate: if not exactly true, no OctoBot call is made and a structured refusal is returned. It also clarifies that the same confirm=true gate applies for LIVE and SIMULATOR profiles, adding behavioral meaning far beyond the schema's bare boolean field.

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

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

The opening sentence states the exact action and resource: 'Trigger a full OctoBot process restart.' This is distinguished from safety-related siblings like wait_for_octobot_ready by explicitly framing itself as the restart trigger and referencing the subsequent readiness check, so an agent can tell it apart.

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 an explicit ordered check: confirm must be exactly true, active jobs must not be queued/running, and only then is the live call made. It states hard refusals instead of warn-and-proceed, and explicitly requires the caller to cancel_job or wait before restarting, providing clear when-to-use and when-not-to-use conditions.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it excels. It reveals that the underlying HTTP route always returns 200 even on silent failure, explains the internal NoProfileError handling, and specifies that this tool re-fetches the current profile and raises ProfileSelectionFailedError instead of trusting the status. This is far beyond typical transparency.

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

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

The description is longer than average but every sentence earns its place, given the subtle HTTP 200 failure mode that must be explained. It is front-loaded with a clear purpose and then logically walks through the spec correction, the tool's compensating behavior, the output format, and idempotency. A small amount of redundancy exists around the repeated 200 status, but overall it is 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 single-parameter tool with no annotations and no output schema, the description is remarkably complete. It specifies the output shape, the failure exception, idempotency, confirmation behavior, and the underlying route. An agent has everything it needs to invoke the tool correctly and interpret the result.

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

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

Schema coverage is 0%, so the description must compensate for the single required parameter. It references profile_id throughout and clarifies that an unknown profile_id triggers failure detection and a raised exception, implying it must be an existing profile identifier. It could explicitly point to list_profiles for valid IDs, but the semantics are sufficiently clear from context.

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

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

The description opens with a specific verb and resource: 'Select a profile as OctoBot's current/active profile.' This clearly distinguishes the tool from sibling profile tools like list_profiles, get_profile, create_profile, update_profile, and delete_profile. Even without reading the schema, an agent knows exactly what operation this tool performs.

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 to use the tool: to change the active profile. It also states the operation is idempotent and not confirm-gated, which clarifies expected behavior. However, it does not explicitly name alternatives or state when not to use it, though the purpose itself makes the primary use case obvious.

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

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

With no annotations to convey safety or side effects, the description carries the full burden and fully delivers. It discloses asynchronous scheduling via asyncio.create_task, immediate 'queued' state, background-watcher error surfacing, optional progress notifications, and that no live trading or data destruction occurs.

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 the complexity justifies the length: 14 bare parameters, no annotations, and no output schema. It is front-loaded with the core purpose and then organized into clear mode bullets and labeled sections, so an agent can quickly extract the relevant path.

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 nearly exhaustive for this tool's complexity: it covers call semantics, mode-specific requirements, defaults, error types, output shape, polling/results behavior, and even progressToken behavior. The lack of an output schema is compensated by explicitly stating the returned JSON structure.

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

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

Despite 0% schema description coverage, the description compensates thoroughly: it defines the 'mode' variants, requires 'files' to be a non-empty list of exact names, specifies epoch-millisecond units for timestamps, documents defaults such as 'run_on_common_part_only', explains the conditional requirement for 'exchange_id', and enumerates valid 'exchange_type' values. Remaining parameters are either self-explanatory by name or covered by the note that unused mode-specific parameters are ignored.

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

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

The first sentence states a specific action ('Start a real OctoBot backtest run') and a distinctive behavioral property ('in the background and return immediately'), which clearly differentiates it from job-status, job-result, and data-management siblings. The scope is further clarified by 'never touches live trading or destroys data.'

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 separates the two mutually exclusive modes, explains which parameters apply to each, and names the exact follow-up tools to use: 'Poll get_job_status(job_id)' and 'call get_job_result(job_id)'. It also tells the agent when a call will fail synchronously versus asynchronously, which is essential for correct usage.

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

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

With no annotations provided, the description carries the full disclosure burden, and it does so thoroughly. It covers background execution, immediate return, lock semantics, watcher behavior, error propagation, known OctoBot-side limitations, and cancellation signals. There is no contradiction with annotations because none exist.

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 action and is well-structured with clear sections. It is quite long and contains repeated references to session confirmations and docstrings that could be tightened, but the density of useful behavioral information justifies most of the length.

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

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

Given no output schema and no annotations, the description provides a complete operational picture: immediate output shape, asynchronous job lifecycle, polling endpoints, final result contents, error messages, cancellation path, and a known upstream failure mode. An agent has everything it needs to invoke and monitor this 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?

Schema description coverage is 0%, so the description must compensate, and it does. It explains that symbols must be non-empty, time_frames is optional with OctoBot's default set, start/end_timestamp are optional epoch milliseconds, and exchange values should be discovered via get_all_symbols. This adds meaning well beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Start a real OctoBot historical data collection run in the background and return immediately.' It clearly distinguishes this from backtesting, references the exact endpoint, and makes the tool's scope unmistakable.

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

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

The description explicitly tells the agent how to discover valid values via get_all_symbols and get_available_timeframes_for_collection, when to poll get_job_status, when to read get_job_result, and when to cancel via cancel_job. It also clarifies the concurrency relationship with start_backtest, so an agent knows when this tool is appropriate.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses mutation, the default additive behavior, the side effects of deactivate_others, that only evaluator subtypes are affected and never trading modes/strategies, that the tool is not confirm-gated, that it raises EvaluatorConfigUpdateRejectedError on non-2xx responses, and that the error text is empty in practice.

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 and information-rich, but long. References to module docstrings and open questions add provenance yet could be trimmed. It is front-loaded with purpose and endpoint mapping, and every paragraph contributes actionable detail.

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 zero annotations, no output schema, and a deceptively simple input schema, the description is remarkably complete. It covers the exact request-body shape, parameter derivation, example class names, output envelope, error behavior, and the discovery path through list_evaluators().

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

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

Schema description coverage is 0%, but the description fully compensates. It explains that patch keys must be evaluator class names with real examples, values can be booleans or 'true'/'false' strings, the patch is submitted as-is unwrapped, and deactivate_others default and semantics are thoroughly described.

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: 'Update the current profile's evaluator-activation config.' It further distinguishes itself by mapping to POST /config and explaining that patch keys are evaluator class names, so it cannot be confused with sibling tools like update_trading_config or update_tentacle_config.

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 strong practical guidance: use list_evaluators() to discover exact class names and current activation states, and explicitly warns that get_tentacle_config does NOT expose activation state. It also clearly defines when deactivate_others=True versus False. It does not explicitly state a when-not-to-use caveat against sibling update tools, but the contextual signal is strong.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It thoroughly covers the confirm gate, local refusal for underscores, the exact request mapping, the decision to ignore the success response body, secret redaction on failure, and the minimal success output. This is exceptional transparency for a credential-writing 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 long but well-structured and front-loaded with the one-sentence purpose. The detailed paragraphs are earned given the security-sensitive behavior and lack of annotations, though some internal references (e.g., 'open question #2, now resolved', 'see this module's docstring') add noise and could be trimmed.

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 5-parameter tool with no output schema and no annotations, this description is remarkably complete. It specifies input semantics, confirmation behavior, local validation, failure handling, the success response shape, and why the response body is never forwarded. An agent has enough information to call this tool safely and interpret its result.

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

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

Schema description coverage is 0%, so the description must compensate, and it does. It explains the exact meaning and effect of exchange, api_key, api_secret, api_password, and confirm, including the requirement for confirm to be exactly true and the underscore restriction on exchange. Every parameter's role is semantically enriched beyond the raw schema.

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

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

The description opens with a specific verb and resource: 'Write an exchange's API credentials to OctoBot's global config.' This clearly identifies what the tool does and naturally distinguishes it from sibling tools focused on trading config, evaluator config, or profile management.

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 intended use is strongly implied by the purpose statement: use this tool to write exchange API credentials into the global config. It does not explicitly name alternatives or exclusions, but the operation is specific enough that an agent can tell when it applies. Slightly more explicit routing relative to update_trading_config or update_evaluator_config would make it 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?

With no annotations provided, the description carries the full burden and delivers thoroughly: it discloses the exact endpoint/body mapping, the enum-ordinal encoding trap for risk/complexity with the resulting ValueError/HTTP 500, the silently-ignored config parameter, the active-profile rename rejection with its exact error message, the output shape, and a side-effect disclaimer (not confirm-gated, does not destroy anything, no credentials/live trading).

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 front-loaded with a one-sentence purpose and densely organized with bold spec-correction bullets and a separate output section; nearly every sentence earns its place given the tool's traps. Minor verbosity in the live-reproduction narrative (exact error string, source path references) prevents a perfect score.

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

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

There is no output schema and no annotations, so the description must cover return values and side effects — it does, including the exact output contract and the two failure modes with their surfaced error type. For a tool with hidden traps (enum encoding, ignored config, active-profile restriction), an agent has everything needed to call it correctly.

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

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

Schema description coverage is 0% and the schema only types patch as a generic object with additionalProperties true. The description compensates by naming the meaningful patch keys (risk, complexity, config), specifying the required int/enum-ordinal encoding for risk and complexity, mapping profile_id to the body's id field, and noting that updated_fields echoes the sent patch.

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: "Update an existing profile's metadata" and immediately adds a scope constraint ("never the active/selected profile's name"). This boundary condition, reinforced later by the active-profile rename rejection, makes the tool easy to distinguish from sibling create_profile, delete_profile, and select_profile without ambiguity.

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 provides a clear when-not in the first sentence (never rename the active/selected profile) and explicitly warns that patch['config'] silently has no effect against the current OctoBot version, so an agent knows not to attempt it. However, it never names sibling alternatives or states conditions for choosing this tool over them, so it stops short of full routing guidance.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses mutation without data destruction, exact success and failure response shapes, live-confirmed error behavior, the non-JSON error body despite the JSON content-type header, and the raised exception on non-2xx responses.

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 and information-rich; nearly every sentence adds operational value. It is front-loaded with the core update semantics and endpoint, with verification details placed later. Slight redundancy exists in repeating the output shape and the route, but overall it is justified for a tool with no schema coverage.

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 mutation tool with no annotations, no output schema, and 0% parameter schema coverage, this description is exceptionally complete. It covers the HTTP mapping, request body shape, exact success/failure bodies, error handling, output format, side-effect profile, and confirmation gate status.

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

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

Schema description coverage is 0%, so the description must compensate. It does by explaining that patch is the raw unwrapped patch dict sent as the JSON body, and that tentacle names the tentacle. It adds meaning beyond the minimal schema, though it stops short of giving concrete example values or enumerating valid patch fields.

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

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

States a specific verb and resource: 'Update one tentacle's configuration for the currently active profile.' The endpoint mapping and the explicit note that the batch route exists but is deliberately not exposed clearly distinguish this tool from related operations.

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?

Clearly scoped to a single tentacle and the active profile, and it explicitly warns that the batch route is not available here. It does not enumerate sibling alternatives like get_tentacle_config or list_tentacles, but the read/update distinction is implicit and the context is strong enough for an agent to select it 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?

With no annotations provided, the description carries the full burden, and it excels: it explicitly states the mutation is not confirm-gated, does not destroy data, expose credentials, or enable live trading. It also discloses error behavior (TradingConfigUpdateRejectedError on non-2xx) and clarifies that OctoBot's error text is empty in practice, which is valuable beyond the schema.

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

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

The description is front-loaded with the purpose and contains a logical structure, but it is verbose. References to 'module docstring', 'spec's [V]-tagged claim', and 'independently re-confirmed this session' are unnecessary for tool invocation and add noise. It could be trimmed without losing essential information.

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

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

For a mutation tool with no annotations and no output schema, the description is remarkably complete. It covers the request mapping, parameter shape, output shape, safety profile, and error behavior, leaving little for an agent to guess.

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% and the schema only says patch is an object with additionalProperties. The description compensates fully by explaining that patch is submitted as-is, unwrapped, and typically maps tentacle class names to booleans or 'true'/'false' strings. This is exactly the semantic detail an agent needs.

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

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

The description opens with a specific verb and resource: 'Update the current profile's trading-mode tentacle-activation config.' It clearly identifies what the tool does and even maps it to POST /config. However, it does not explicitly differentiate itself from sibling tools like update_tentacle_config or update_evaluator_config, so it misses the top score.

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 intended use is implied by the purpose statement: you use this when you need to update the current profile's trading-mode tentacle activation config. The description does not provide explicit when-not-to-use guidance or name alternative tools, and it lacks prerequisites or selection criteria.

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

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

With no annotations provided, the description carries the full behavioral burden and does so thoroughly: it discloses that the loop is bounded, never raises on timeout, returns an honest false, requires at least one failed poll before ready:true, and clarifies that 'ready' only means the HTTP server answered after a confirmed outage. This is exceptionally transparent about edge cases 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?

The description is front-loaded with the core purpose and then provides deeply relevant behavioral, correctness, and parameter context. It is long and contains project-specific references (ADR-0010, NFR-3, open question #14) that could be condensed without losing operational value, so it is not maximally concise.

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

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

Given no output schema and no annotations, the description is unusually complete: it specifies return fields, timing semantics, failure behavior, default reasoning, measurement caveats, and a confirmed limitation. Nothing an agent needs to invoke this tool correctly or interpret its result is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does. It explains the default timeout and poll interval, why those values were chosen, gives measured real-world timing context, and instructs users to override both per-call if their environment differs materially.

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

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

The first sentence states a specific verb and resource: polls for OctoBot's HTTP server becoming reachable again after a restart. It also clarifies the exact meaning of 'ready' and distinguishes this tool from generic polling or restart tools in the sibling list.

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

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

The description clearly frames when this tool applies (after a restart) and explicitly warns against using it as a fix for evaluator/strategy-composition tuning validation. It does not name an alternative sibling tool, but it gives strong context about its intended pairing with restart_octobot and its read-only nature.

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