Manawa Terminal

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

Annotations only declare readOnly=false and destructive=false, so the description carries real weight and does: filled vs pending semantics, idempotency guidance, "A refused error is a portfolio rule. Do not shrink the order... Do not rewrite that error into a success," future dates refused, HIL/limit card behavior, and concrete side effects (cash rises on a long dividend, share count unchanged, open cost reduced). That is well beyond what the annotations provide.

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

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

It is front-loaded with purpose and ends with an Args block, but the middle is ~500 words of dense prose that repeats short/cover and dividend rules already restated in the Args list. Several sentences are garbled or hard to parse ("the order above Skip HIL up to," "records the price after that day's range check"), so size and phrasing cost it.

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 14-parameter, high-stakes mutation with thin schema docs and an output schema that covers returns, the description supplies nearly everything needed: date format, ordering preconditions, asset-class rules, and error semantics. Residual ambiguity remains around price being described as required while the schema marks it optional, and how to recover from a rejected order other than not retrying.

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

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

With schema coverage at 14% and zero enums declared, the description is the only source of allowed values, and it supplies them all: side (buy/sell/deposit/withdrawal/dividend/short/cover), order_type (market/limit), expires_kind (gtc/day/delete_after), on_touch (review/direct), plus per-param meanings such as $CASH for deposits and expires_at only under delete_after. It also clarifies the awkward price-vs-limit_price relationship.

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 the specific verb and resource (add a transaction to a portfolio) and enumerates the exact side values it supports, so an agent can distinguish it from edit_order or cancel_order without inspecting the schema. The document-attachment and order-type paragraphs stay on the same subject.

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

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

It gives explicit preconditions and sibling pointers: "Call get_portfolio_rules first and size it to those rules," use search_library/list_library_items to obtain the case id, list_strategies for strategy_id, and "do not send a second order" when pending. It never says when to use edit_order or cancel_order instead, which is the only routing gap.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description adds a genuinely useful behavioral detail — 'No fill is written' — clarifying that cancellation does not produce a fill record. It stops short of stating irreversibility or permission requirements.

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

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

Front-loaded with the action and the key side-effect ('No fill is written') in two short sentences. The trailing 'Args:' block is Python docstring boilerplate that partly duplicates schema titles, but it costs little.

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

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

Output schema exists, so return values need not be explained, and annotations cover destructiveness. Still missing: the failure mode when the order is not open, and whether strategy_id must match the order's strategy. Adequate but with clear gaps for a destructive mutation.

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 only 33%, so the description must compensate. It does label portfolio_id and order_id as UUIDs, which the bare schema titles omit, but it silently ignores the optional strategy_id parameter, whose own schema description is the only documented one. Baseline 3 fits given partial compensation.

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: 'Cancel an open portfolio order.' That is unambiguous and distinguishable from edit_order, though the description never names the sibling it is not (edit_order could also plausibly alter an order).

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 word 'open' implies a state precondition (only open orders can be cancelled), which is the only usage guidance present. There is no explicit when/when-not, no mention of edit_order as the alternative for modifying an existing order, and no statement of what happens if the order is already filled.

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

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

Beyond the annotations (readOnly=false, destructive=false, openWorld=false), the description discloses persistence ('Calling this stores the alert'), lifecycle semantics (max_fires before it leaves Active), firing-time agent behavior (agent_instruction, rule_ref section read when STRATEGY_ALERTS=1), and off-hours gating tied to ALERT_OFF_HOURS=1. Those are behavioral facts an agent cannot infer from the annotation set.

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

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

Front-loaded with the one-line purpose, then a clean per-parameter Args list where each entry adds new information rather than restating the schema. It is long, but with 20 parameters that length is mostly earned; a little tightening (e.g. the separate 'Calling this stores the alert' line) would make it a 5.

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 20-parameter mutation with an output schema that already covers return values, the description reaches nearly everything an agent needs: type-specific required fields, mutual exclusion, defaults, and timezone handling. Gaps are minor — it never states that alert_type must always be supplied, and it says nothing about validation failure behavior or duplicate alerts.

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 only 5% and there are zero enums in the schema, so the description carries the burden — and it does: it supplies the alert_type, direction, and schedule_repeat value sets, the above/below/either vs long/short distinction, the trailing give-back mechanics, the 0 < x <= 50 bound, and the exactly-one-of trail_pct/trail_amount constraint. Only strategy_id is left to the schema, which already documents it.

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 verb (create) plus the four alert flavors it can produce — price, event, clock, trailing — and the Args block enumerates the five allowed alert_type values. That is enough to separate it from list_alerts and delete_alert in the sibling set without opening a schema.

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?

Guidance is conditional and explicit: which alert types require symbol, threshold, event_types, schedule_at, and exactly-one-of trail_pct/trail_amount. It does not name an alternative tool or an explicit 'do not use this for X' case, so it stops 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, openWorldHint=false, so the safety profile is covered. Beyond that the description adds essentially nothing: it does not say what happens on duplicate names, whether a nonexistent parent_id errors, or any side effects of creating a folder. Since an output schema exists, return format need not be explained, but mutation-edge behavior is left unaddressed.

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?

One-line purpose sentence followed by a compact Args block; front-loaded and free of padding. The Args list largely duplicates schema titles, which is mild waste but not harmful.

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 3-parameter mutation tool with an output schema and annotations, the definition covers the primary flow but omits the strategy_id parameter entirely and says nothing about parent validation or conflicts. Adequate to call correctly in the common case, incomplete at the edges.

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 33% (only strategy_id is documented in the schema). The description covers name and parent_id and adds real meaning with 'omit for a root folder', but it silently ignores the third parameter, strategy_id, whose strategy association is significant for a write operation.

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 library folder, with the nesting capability named up front. The name alone distinguishes it from create_library_item and move/rename_library_folder among siblings, but the description itself never draws that contrast.

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?

There is no guidance about when to use this instead of create_library_item, move_library_folder, or rename_library_folder, and no prerequisites (e.g. whether the parent folder must already exist). Only usage hint is 'omit for a root folder', which is parameter behavior, not tool selection.

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

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

Annotations already declare this is a non-read-only, non-destructive, closed-world operation, so the safety profile is covered. The description adds useful context that HTML is stored as source and that folder_id may be omitted for the root, but it does not discuss permissions, duplicate handling, or other creation side effects.

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

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

The description is front-loaded with the core action and then uses a compact Args list for parameter context. Every sentence carries useful information, and there is no unnecessary 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 create tool with five parameters, an output schema, and annotations covering safety, the description is largely complete: it explains content formats, folder placement, and content defaults. The main gap is that strategy_id is not mentioned in the description, although the schema itself documents 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?

With schema description coverage at 20%, the description does substantial work by documenting title, content, folder_id, and content_type, including Markdown-versus-HTML behavior and the folder-root default. It omits strategy_id, though that parameter is already described in the schema, and its stated content_type default differs slightly from the schema default of null.

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: create a markdown or HTML document in the research library. This clearly distinguishes it from sibling tools such as create_library_folder, update_library_item, and delete_library_item.

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 explains some parameter behavior, such as omitting folder_id for the library root, but gives no explicit guidance on when to use this tool versus update_library_item, create_library_folder, or other library operations. Usage is implied by the name and purpose rather than stated as a decision rule.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: no duplicate-name behavior, no permission or plan requirements, no statement of what the newly created portfolio contains or whether the call is idempotent. For a mutation tool this is a notable gap.

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

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

The one-line purpose sentence is front-loaded and the Args block is short and scannable. The Args block largely restates schema property titles, so a little space is not earning its place, but the description is far from bloated.

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

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

An output schema exists, so return values need not be explained, and the parameters are effectively covered across description and schema. What remains missing is behavioral context for a write tool: duplicate handling, whether strategy_id links the portfolio or merely tags it, and any cost or rate-limit notes.

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 only 33%, so the description must shoulder more of the load. It does document the two bare schema properties, name and currency, and notably that currency defaults to USD, while strategy_id is already well documented inside the schema itself (UUID from list_strategies, omit when not part of a strategy). The combination is close to complete, but the description offers no format or validation details (currency code style, name constraints).

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: create a portfolio, parameterized by name and base currency. It is clear what the tool produces, but it makes no attempt to distinguish itself from siblings such as list_portfolios or get_portfolio_statistics, which the agent must infer from names 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?

There is no statement of when to use this tool versus alternatives, no prerequisites, and no exclusions. The agent gets no help deciding between create_portfolio and adjacent tools, or what to do if a portfolio with the same name already exists.

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

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

The annotations already establish that this is a non-read-only, non-destructive create operation. The description adds useful behavioral context: scheduled notifications depend on Settings Screener in & out, weekly schedules require Pro, and the baseline can be seeded via last_symbols or run_screener.

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 followed by a structured Args block. It is appropriately sized, though it repeats last_symbols once in prose and again in Args.

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

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

With an output schema available, the description need not explain return values, and the annotations cover safety hints. It is complete enough for an agent to invoke the tool, but it omits strategy_id from the Args block and does not clarify create-vs-update boundaries.

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 only 17%, so the description carries most of the burden. Its Args block explains five of six parameters, including acceptable schedule values, the query blob shape, and how last_symbols seeds the baseline; strategy_id is left to the schema's own description.

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

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

The description states a specific verb and resource: saving a screener filter query for scheduled enter/exit notifications. It distinguishes the creation flow from the run_screener seeding alternative, though it does not explicitly contrast itself with update_screener.

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

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

It gives clear context for when to use the tool: creating a screener for scheduled enter/exit notifications. It also names the seeding alternatives — pass last_symbols or call run_screener after create — but does not explicitly state when to prefer create_screener over update_screener.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered, but the description adds nothing behavioral on top: no indication of what happens on duplicate names, whether symbols are validated, how strategy_id scoping behaves, or what is returned. The 'Args' block merely restates schema fields rather than adding 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 first sentence is front-loaded and sufficient; the Args block is short but largely redundant with the schema field names. It is efficiently sized overall, just with some duplicated 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?

Because an output schema exists, return values need not be described. However, for a mutation tool that creates a named entity, the description should say something about name uniqueness or how strategy_id ties the watchlist to a strategy; that context 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 description coverage is 33%, but the description does document both required parameters and adds a concrete example for symbols (["AAPL", "MSFT"]), which the schema lacks. The third parameter, strategy_id, is left entirely to its schema description, so the description covers the essentials without fully compensating for the coverage gap.

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

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

The description states a specific verb and resource ('Create a watchlist') plus the two required inputs, so an agent knows exactly what the tool produces. It does not, however, distinguish it from the other create_* siblings (create_portfolio, create_screener) or from update_watchlist, so differentiation is left to 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?

There is no statement of when to use this rather than create_portfolio, create_screener, or update_watchlist, and no prerequisites or exclusions. The agent must infer the choice purely from the tool name.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and openWorldHint=false, so the safety profile is carried by structured data. The description adds nothing beyond that — it does not say deletion is permanent, whether it can be undone, or how strategy_id scoping affects the operation, so it earns no credit above the annotation baseline.

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?

One sentence plus a single arg note — front-loaded and free of waste. The boilerplate 'Args:' block is minor clutter but not costly.

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?

An output schema exists, so return values need no explanation, and annotations cover the destructive nature. However, the description never explains what strategy_id does in the context of a delete (whether it scopes the deletion or just is metadata), which is a meaningful gap for a mutation with two parameters.

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

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

Schema coverage is 50%: strategy_id is well documented in the schema, but alert_id has only a title. The description compensates by specifying that alert_id is 'The alert UUID', which is the format information an agent needs and which the schema does not provide.

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 ('Delete an alert by ID'), which an agent can cleanly separate from siblings like create_alert, list_alerts, and the unrelated delete_screener/delete_library_item tools. It does not explicitly name those siblings, but the verb+resource pair 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?

There is no guidance on when to use this tool versus alternatives, no prerequisite (e.g., alert must exist, must belong to the caller), and no mention of irreversibility. An agent must infer the entire usage context from the name alone.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the safety profile is covered. The description contributes one genuinely additive fact — that the delete cascades to everything inside the folder — but says nothing about permanence/irreversibility, permission requirements, or whether a confirmation step exists.

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

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

The core sentence is front-loaded and wastes nothing. The Args block is boilerplate that restates a single parameter, but it is short enough not to hurt scannability.

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

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

With an output schema present, return values need no explanation, and the cascade scope is disclosed. However, for a destructive operation with an optional strategy_id parameter, the description omits reversibility, permissions, and when strategy_id should be supplied, leaving real gaps.

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

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

Schema coverage is 50%: strategy_id is thoroughly documented in the schema, while folder_id has no schema description, so the description's "The folder UUID" is the only hint about its format. That is a small but real addition, landing at the baseline for partial 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?

States a specific verb and resource ("Delete a library folder") and adds scope ("and everything inside it"), which is meaningfully more precise than the title. It doesn't name any sibling such as delete_library_item to disambiguate, so it stops short of a 5.

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?

There is no indication of when to use this versus delete_library_item, move_library_folder, or create_library_folder, nor any prerequisite such as ownership or whether nested contents must be considered first. The only usage-relevant signal is the implicit cascade warning embedded in the purpose sentence.

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

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

Annotations already flag destructiveHint=true, so the safety profile is known; the description adds the non-obvious behavioral fact that all stored versions are deleted too, which the annotations do not convey. It still omits whether deletion is permanent/undoable and does not mention the optional strategy_id.

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?

One sentence plus a short arg line; front-loaded with the action and scope. The Args block is somewhat redundant with the schema but is compact and introduces no fluff.

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

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

An output schema exists and annotations cover the destructive/write profile, so the remaining burden is modest. Still, a destructive cascade delete would benefit from stating permanence and how strategy_id affects behavior.

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 50%. The description documents item_id as a UUID, but that barely extends what the schema title already implies, and it says nothing about the optional strategy_id — that parameter is covered only by the schema's own description.

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

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

States a specific verb (delete) and resource (library document) and adds the important scope detail that all stored versions go with it. It is distinguishable from delete_library_folder and the other delete_* siblings, though it does not explicitly name them.

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

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

No guidance on when to use this rather than delete_library_folder, update_library_item, or a version-level removal. No prerequisites, no warning about irreversibility, and no exclusions are given.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the description is not required to re-state danger, but it also adds nothing: no mention of permanence, no per-ID vs bulk semantics, no effect on dependent strategies. For a destructive mutation the description should confirm irreversibility rather than just repeat the tool name.

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

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

Two short elements, front-loaded with the action and key, with no filler. The Args block largely restates the schema but earns its place by naming the sibling that supplies the ID.

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?

An output schema exists, so return values need no explanation, and the one required parameter is covered. However, for an irreversible delete with a secondary strategy_id parameter whose relevance is unexplained, the definition leaves real gaps an agent would face at call time.

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 50%: strategy_id is fully documented inline, while screener_id carries no schema description, and the description compensates by explaining it is the UUID obtained from list_screeners. That covers both parameters adequately, though it says nothing about what strategy_id means for a delete operation.

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 ('Delete a saved screener') plus the lookup key scoping it ('by ID'), which cleanly separates it from list_screeners, run_screener and update_screener. It stops short of contrasting itself against siblings explicitly, but the operation 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 only procedural hint is where to obtain the ID ('from list_screeners'); there is no statement of when deletion is appropriate, no prerequisites, and no warning about irreversible removal or what happens to screeners referenced by a strategy. The agent is left to infer all 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?

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), so the description's job is to add context, which it does: it discloses that results include the print and price move, not just transcript text, and warns against fabricated symbols. It does not discuss volume limits or how results are scoped per call, so it falls short of fully rich 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?

Front-loaded with purpose, then usage, then arguments — the right order. The Args list is long but earns its space given 7% schema coverage. A few sentences are telegraphic to the point of ambiguity ('Do not invent symbols.', 'plus the print') and could be tightened into flowing 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?

With 14 parameters, an output schema, and full annotations, the definition covers the essentials an agent needs to call it correctly. Remaining holes are combinatorial: what happens if neither tickers nor sector is supplied, and whether date-based and fiscal-based ranges are mutually exclusive, are left implicit, and strategy_id is undocumented.

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 7%, so the description must carry the load, and its Args block does exactly that: date formats (YYYY-MM-DD), season pairing rules (conference_from with conference_to, compare_from with compare_to, fiscal_year with fiscal_quarter), value ranges (1-8, 1-5, quarter 1-4), the default of 3, the 'not used with compare' restriction, and a sector disambiguation ('Banks, insurers, and brokers are Financials'). The gap is strategy_id, which appears in the schema with its own description but is omitted from the Args list entirely.

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 — retrieve what was said on earnings calls, plus the print and the price move — which is more than a restatement of the name. It then explicitly separates itself from finance_search (report dates, Earnings Deep Dive, full transcript), so an agent can route without opening either schema.

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?

Gives concrete usage shapes (one season across several names, or this season versus a prior season), the two selection paths (tickers you already have vs. a sector label), and an explicit exclusion routing to the sibling finance_search. The constraint 'Do not invent symbols' and the note that 'Optional when sector is set' also imply the fallback when tickers are absent.

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 only declare the generic safety profile (readOnlyHint=false, destructiveHint=false), so the description adds real value: it discloses the HIL/accept-card re-approval trigger, the open-session requirement for day orders, and that GTC orders can persist through a closed session. The phrasing of the approval sentence ('HIL on, or an order above Skip HIL up to, opens the accept card again') is garbled enough to blunt some of that value.

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?

Purpose and the cancel_order hand-off are front-loaded, but library_item_id is explained twice (body prose plus Args block) and the approval/session sentences are dense and hard to parse. The Args section is worthwhile, yet the prose duplicates it rather than complementing it.

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 9-parameter mutation with an output schema and safety annotations, the description covers the approval workflow, session constraints, and the tricky parameters. It lacks error/failure behavior when the order is no longer open, which is the main remaining gap.

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 only 22% and expires_kind has no enum in the schema, yet the description enumerates its allowed values (day, gtc, delete_after) with the 90-day GTC meaning, states expires_at is required with delete_after and that naive times are New York, and explains empty-string semantics for library_item_id. This compensates well beyond the structured 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?

Opens with a specific verb and resource ('Change an open portfolio order') and names the scope qualifier (open) plus the sibling it precedes (cancel_order). An agent can distinguish this from cancel_order or update_watchlist without opening any schema.

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

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

Explicitly routes sequencing: 'Use this before cancel_order.' and instructs 'Send only the fields that change.' However, it never states when NOT to use it (e.g. on filled/closed orders) or what happens if the order is not open, so exclusions are left implicit.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false. The description adds useful behavioral context: it returns an answer with an inline widget, describes exclusive focus modes, explains that focus=raw produces a thin data slice, and notes that strategy_id is retained on the result card.

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 purpose is front-loaded in the first sentence, but the section parameter expands into a very long, dense catalog of edge cases and routing rules. Much of it may be useful, but the overall description is overstuffed and difficult to scan.

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

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

For a complex search tool with no output schema and no schema parameter descriptions, the description is largely complete: it explains the return shape at a high level, documents all parameters, and covers Deep Dive modes. It could still be clearer about the exact response format beyond 'answer with an inline widget'.

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

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

Schema description coverage is 0%, so the description carries the full parameter-documentation burden. It supplies meaningful guidance for query, symbols, section, focus, source, and strategy_id, including extensive section routing, though the source list is incomplete with an ellipsis and the section guidance is dense and hard to parse.

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: search financial data and return an answer with an inline widget. It also scopes the asset classes and Deep Dive modes, making the tool's purpose clear, though it does not directly name when to choose it over sibling run_deepdive.

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

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

It gives concrete usage context: pass the user's question without rephrasing, use list_watchlists or list_portfolios before screening symbols, and use focus modes when a Deep Dive exists. It also provides many section-routing exclusions, but lacks a crisp tool-level comparison against alternatives such as run_deepdive or earnings_rag.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds non-obvious behavioral context — that draft ids fail until EOD generation, implying failed lookups rather than empty results — which annotations cannot express. It does not describe error semantics precisely (what a rejected draft id returns), keeping it below 5.

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

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

Two tight sentences front-load the action and the id-source precondition, with the constraint before the args block. The "Args:" section is partly redundant with the schema's required entry_id, but it is short and the substance 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?

An output schema exists, so return shape need not be explained. The one thing an agent could get wrong — passing a draft id — is called out with the fix, and the id format ambiguity (integer vs legacy UUID) is resolved. Adequate for a two-parameter read tool.

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

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

Schema coverage is 50%: entry_id has no schema description but is documented here as coming from list_journal and accepting integer or legacy UUID, which is the meaningful detail. The optional strategy_id is never mentioned in the description, leaving half the parameter surface to a schema entry that reads as boilerplate from another 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?

States a specific verb and resource ("Get a full generated journal entry by ID") and immediately attributes the id source to list_journal, distinguishing it from sibling list_journal and from submit_journal_draft. An agent can tell exactly what this returns versus the list tool without opening the schema.

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

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

Explicitly states the precondition (ids must come from list_journal) and the negative case (draft ids from submit_journal_draft are unreadable until the end-of-day generation), plus the remedy (use list_journal after the daily run). This is a genuine when-to-use / when-not-to-use pair with a named alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds useful content-format context (markdown, raw HTML, signed PDF URL), but does not mention error behavior, auth needs, or signed URL expiry.

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 short, front-loaded with the core action, and includes only relevant output-type detail. Every sentence and the Args note earn their 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?

For a read-only get-by-id tool with an output schema and annotations, the description is largely complete. It covers the required identifier and content formats, though it omits how to find the item or when to choose search/list instead.

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 50%: item_id is documented only in the description as a UUID, while strategy_id is well documented in the schema. The description adequately covers the missing required parameter but does not explain the optional strategy_id in the prose.

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: get a library document's metadata and content. It also clarifies the content representation, making the tool's purpose immediately distinguishable from list/search 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?

It implies usage by requiring item_id, but gives no explicit when-to-use guidance, no comparison to list_library_items or search_library, and no explanation of how to obtain the item UUID.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: default unread filtering, history includes already-read alerts, newest-first ordering, and upstream cap details.

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 behavior, then uses a compact Args list for parameter-specific details. Every sentence adds useful information without unnecessary 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?

With an output schema present and annotations covering read-only safety, the description is largely complete for invocation. The main gaps are the absence of explicit sibling differentiation and the omitted strategy_id mention, though the latter is documented in the 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?

Schema description coverage is only 25%, so the description must compensate. It does so for offset, limit, and history by explaining paging, defaults, max values, and the unread upstream cap. It does not mention strategy_id in the description, but that parameter is covered by the schema itself.

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: 'Get alert notifications', and clarifies the default unread scope. It is clear what the tool does, but it does not explicitly differentiate itself from the sibling list_alerts tool, which could be confused with notification 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?

It gives a useful default behavior ('Unread only, unless history is set') and explains the history flag. However, it does not explicitly say when to use this tool versus list_alerts or other alert-related siblings, leaving the agent to infer the distinction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered structurally. The description adds only the UI location and the list of toggle categories, which is mild context. It says nothing about scoping behavior when strategy_id is present or absent, does not describe errors or auth requirements, and the '(T06)' reference is an internal ticket marker that conveys nothing to an agent.

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

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

Two short sentences with the purpose front-loaded, so there is no real bloat. The '(T06)' fragment and a stray newline are the only wasted tokens.

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?

This is a simple read-only, single-optional-parameter tool with rich annotations and an output schema, so the description needn't explain return values or pagination. What remains — what the resource is and which toggles it covers — is stated. Only a minor gap exists around how strategy_id affects the returned scope, which the schema already partly addresses.

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

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

Schema description coverage is 100% and the strategy_id field already explains the UUID provenance and the omit-when-not-in-a-strategy rule. The description adds no further parameter meaning, so the baseline 3 applies — the schema does all the work here.

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?

Specific verb+resource: 'Read the account's notification preferences', which clearly separates it from the write-side sibling update_notification_settings. The parenthetical UI breadcrumb (Settings → Notifications) reinforces the scope, though the description never explicitly names the sibling it is not.

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 when-to-use or when-not guidance is offered, and the obvious counterpart, update_notification_settings, is not mentioned. The agent must infer on its own that this is the read path and that mutations belong elsewhere.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces this with 'This tool cannot change the rules,' which is a useful, non-contradictory confirmation. It also discloses what the return conceptually contains (allowed assets, max order size), though the output schema carries the detail.

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

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

Front-loaded with the core purpose, then the usage trigger, then the safety caveat, then the args. Every line earns its place and there is no filler.

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

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

For a read-only lookup with an output schema and safety annotations already present, the description supplies everything an agent needs: purpose, pre-call requirement, constraint on mutability, and the required identifier.

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 50%: portfolio_id has no schema description, but the Args block supplies 'The portfolio UUID', filling that gap, while strategy_id is well documented in the schema itself. Between the two sources both parameters are covered, though the description's own contribution is minimal beyond type restatement.

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+resource ('Read the order limits for a portfolio') and then concretizes what those rules contain — allowed assets and maximum order size. This separates it cleanly from siblings like get_portfolio_statistics or add_transaction.

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?

Gives an explicit trigger: call before add_transaction for buy, sell, short, or cover, which names the alternative tool and the condition that selects this one. It does not state when the tool is unnecessary (e.g., cancel_order or non-trading flows), so it falls short of full when/when-not coverage.

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

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

Annotations already make clear this is a read-only, non-destructive, closed-world operation. The description adds valuable domain caveats beyond annotations, including currency basis for exposures, negative weight and dividend_income cases, and the warning not to add dividend_income on top of total_gain.

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 compact, relevant caveats for interpreting the statistics. The Args section is somewhat redundant with the schema, but the UUID clarification and output warnings earn their space.

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 presence of an output schema and read-only annotations, the description is largely complete enough to invoke the tool correctly. It covers the required parameter and important output interpretation pitfalls, though it lacks routing guidance against sibling tools.

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 only 50%. The description compensates for portfolio_id by clarifying that it is a UUID, but it does not mention strategy_id, which is instead documented richly in the schema. This is adequate but leaves the agent relying on the schema for half the parameter 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 states a specific verb and resource: 'Get portfolio performance statistics,' and enumerates the included metric families (returns, allocation, risk). It does not explicitly differentiate this tool from related siblings such as get_positions or list_portfolios, so it is clear but not sibling-aware.

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 the tool is used to retrieve portfolio statistics, but it gives no explicit when-to-use guidance, prerequisites, or alternatives. An agent must infer that get_positions or list_portfolios are different and when this stats tool is preferable.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine domain behavior that annotations cannot: how shorts are represented (negative shares, positive avg_cost, negative cost book, negative market value), that cash includes short proceeds and is reduced by owed dividends, and that open cost of a long is net of held dividends. That materially changes how an agent interprets the returned numbers.

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 core purpose is front-loaded in the first sentence, and the accounting notes are dense but each one earns its place by disambiguating sign conventions. The trailing 'Args: portfolio_id: The portfolio UUID' is largely redundant with the schema and the strategy_id parameter is silently omitted from that block.

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?

An output schema exists, so return shape needn't be spelled out; the description instead covers the non-obvious interpretation rules, and it clearly separates itself from the statistics tool. For a two-parameter read-only query, 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?

Schema coverage is 50%: strategy_id is well documented in the schema, while portfolio_id only says 'The portfolio UUID', which the description echoes without adding syntax or constraints. No enum or format detail is provided beyond the bare type, so the description roughly matches rather than exceeds the schema.

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

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

States a specific verb and resource ('Get current holdings') plus the exact fields returned (quantity, cost basis, market value, unrealized P&L), and explicitly routes realized P&L to get_portfolio_statistics. An agent can distinguish this from get_portfolio_statistics without opening either schema.

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?

Names one alternative (get_portfolio_statistics) and the condition that selects it (realized P&L from closed longs/shorts), which is useful routing. However, there is no guidance on when to prefer this over list_portfolios or other portfolio-scoped tools, and prerequisites (auth, portfolio existence) are not 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?

Annotations already declare readOnly, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-obvious behavior: the playbook text is returned in full and is not truncated at the usual response size, which affects how an agent should consume the result.

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

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

Front-loaded with purpose then caveat, with no filler. The second sentence ('It is not cut at the usual response size') restates the first slightly, but it reinforces an important operational fact rather than adding noise.

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?

An output schema exists so return-shape explanation isn't needed, both parameters are semantically documented, and the truncation caveat covers the main behavioral surprise. Nothing an agent needs to invoke this 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%, so the description must carry the load, and it does: strategy_id is a UUID sourced from list_strategies, and generation is an optional GCS generation pointer from list_strategy_versions for older saves. Both parameters gain meaning beyond their bare string types.

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 (read), singular resource (one strategy), and scope (current or historical generation), plus what content is included (markdown, settings, links). This clearly separates it from list_strategies and list_strategy_versions in the sibling set.

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?

Names where each ID comes from — strategy_id from list_strategies, generation from list_strategy_versions — which implicitly routes the agent to the right sibling before calling. It doesn't explicitly state when to prefer this over list_strategies, but the singular-scope framing makes the distinction 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds real context on top: the results are scoped to the authenticated user, three alert categories are returned, and the skill_id/rule_ref fields are explained as pointers into strategy rules. It stops short of describing ordering, total counts, or whether filters 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?

Front-loaded with the core statement, then a focused note on skill_id/rule_ref, then a compact Args block. The default values repeat the schema, but the max-100 cap earns that space; the parenthetical explanation of rule_ref is slightly wordier than needed.

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?

An output schema exists, so return-value explanation is rightly omitted, and the annotation set covers safety. The gap is the unexplained strategy_id parameter: for a listing tool, an agent needs to know whether passing a strategy id filters the results or merely scopes attribution, and neither the description nor the schema answers that.

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 Args block adds the meaningful detail that limit is capped at 100, which the schema does not state, and restates the offset/limit defaults. It never mentions strategy_id — one of the three parameters — and the schema's own strategy_id description is boilerplate about 'the card this call writes', which is mismatched language for a read-only list call and leaves the filter's effect ambiguous.

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 price, event, and clock alerts') plus the scope ('for the authenticated user'), which cleanly separates it from create_alert/delete_alert siblings. It does not, however, distinguish itself from adjacent read tools like get_notifications or list_strategies that an agent might confuse with alert retrieval.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternative. The only directional hint is the embedded note that the agent should read the referenced strategy-rule section when an alert fires, which describes downstream behavior rather than selection between tools.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: the generation-run dependency, the exclusion of drafts, the newest-first ordering, and the 90-day upstream cap.

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

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

Front-loads the core purpose and ordering in the first line, then adds the availability caveat and a compact Args block. The Args section mildly duplicates schema defaults but adds the max/90-day constraints that earn their 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?

With an output schema present, the description needn't explain return values, and it covers ordering, availability timing, and pagination bounds. The only gap is any mention of strategy_id filtering in prose, which is acceptable given the schema's own description.

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

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

Schema coverage is only 33%, so the description carries real weight, and it documents offset and limit with defaults (0, 50) and the max (100), plus the 90-day upstream ceiling. It does not mention strategy_id, but that parameter is already well-described in the schema itself.

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 generated daily research journal entries') plus sort order ('most recent first'). It also implicitly separates itself from submit_journal_draft by noting drafts aren't listed, though it never explicitly contrasts with the sibling get_journal_entry for single-entry retrieval.

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

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

Gives clear context for when data is available: entries appear only after the automatic end-of-day generation run, and drafts from submit_journal_draft aren't visible until then. This pre-empts the main 'why is my draft missing' confusion, but there are no explicit when-not-to-use or alternative pointers.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that it is scoped to the authenticated user's library and supplies pagination details, but it does not disclose ordering, empty results, or other behavioral traits.

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 short and front-loaded with the core purpose, followed by a compact Args section. It is appropriately sized, though the Args section could be trimmed since some defaults are already in the schema.

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 annotations and an output schema, the description is mostly complete: it states scope and pagination behavior. The main omission is strategy_id in the description body, though the schema itself documents that parameter.

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 low at 33%, so the description must compensate. It explains offset as skipping folders and adds a max of 100 for limit, but it mostly repeats defaults already in the schema and does not mention strategy_id, which is documented only in the schema.

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

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

The description clearly states a specific verb and resource: listing folders in the authenticated user's research library. It distinguishes folders from library items implicitly, but does not explicitly contrast with sibling tools like list_library_items or search_library.

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 no guidance on when to use this tool versus alternatives such as list_library_items, search_library, or list_strategies. It implies listing folders, but does not specify conditions, exclusions, or alternatives.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful operational detail beyond that: pagination semantics (offset skips, limit defaults to 50, max 100) and the root-listing behavior. It stops short of describing ordering or whether an empty folder errors.

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 opening sentence front-loads purpose and the root-fallback rule, and the Args block is terse with no filler. The only inefficiency is that a prose Args list duplicates what the schema already names, though it does add the default/max values.

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?

An output schema exists, so return values need not be explained. For a simple paginated read tool with strong annotations, the description covers folder scoping and paging adequately. The one real gap is the unexplained strategy_id parameter.

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 only 25% — only strategy_id is documented in the schema. The description compensates for three of the four parameters by explaining folder_id optionality and offset/limit defaults and the 100 cap. However, it completely omits strategy_id, leaving that parameter's purpose to a schema description that appears to be copy-pasted from another tool ('the card this call writes').

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 clear verb+resource ('List documents in a library folder') and clarifies root-level behavior when no folder is given, which distinguishes it from list_library_folders and get_library_item. It does not explicitly contrast with search_library, which is the nearest ambiguous sibling.

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 root-vs-folder condition is implied by the folder_id argument, giving some usage context. However, there is no explicit guidance on when to use this versus search_library or list_library_item_versions, and no prerequisites or exclusions 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds one genuinely useful behavioral fact — results are ordered newest first — but says nothing about completeness of the history or any limits.

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 core sentence is short and front-loaded with the ordering detail. The trailing 'Args:' block is a docstring artifact but minimal and does not obscure the purpose.

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

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

A simple read-only list tool with annotations covering safety and an output schema covering return values. The description supplies the one thing structured fields don't: the result ordering. Nothing essential for correct invocation 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 50%: strategy_id is fully documented in the schema, while item_id has only a title. The description compensates by stating 'item_id: The item UUID', which clarifies the expected format. That lifts it to baseline 3, but it adds nothing about strategy_id or its interaction with version listing.

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 version history for a library document', with ordering noted ('newest first'). It distinguishes the resource from sibling list tools, though it never explicitly contrasts with list_strategy_versions or get_library_item.

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?

Usage is only implied by the purpose statement — an agent can infer it is for inspecting a document's history, but there is no explicit 'use this when' clause and no mention of alternatives like get_library_item for current content.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered elsewhere. The description contributes only pagination behavior (default 50, max 100), and says nothing about ordering, whether an empty list is possible, or how pagination should terminate — though the output schema covers the return shape.

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

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

One-line purpose followed by a compact Args block; the purpose sentence is front-loaded and there is no filler. The Args repetition of defaults already present in the schema costs a little, but the block stays short.

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

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

The tool is simple and an output schema exists, so return values need not be described. Still, for a paginated list tool the description never explains paging strategy or whether a page smaller than limit signals the end, which is the main thing an agent needs to call it repeatedly and 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 33%, so the description carries real weight: it documents offset and limit and adds a 'max 100' constraint that the schema does not express. However, it ignores strategy_id entirely, which is the only parameter with a schema description and the most semantically ambiguous one available.

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 the authenticated user's portfolios') and the ownership scope is explicit, which separates it from generic portfolio data tools like get_portfolio_statistics. It does not explicitly contrast with siblings such as list_watchlists or list_strategies, but the resource noun is unambiguous enough that an agent can select it.

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

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

No when-to-use or when-not-to-use guidance is given, and no alternative is named even though the sibling set contains list_watchlists, list_screeners, list_strategies and get_positions. The agent must infer that this tool is the portfolio enumeration path purely from the name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is known without the description. The description adds the useful scoping fact that results are limited to the authenticated user's own screeners, but says nothing about result ordering, total counts, or behavior when offset exceeds the collection size.

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?

One front-loaded sentence plus a short args block; nothing is padded. The only waste is restating the defaults (0, 50) that the schema already declares, which slightly duplicates structured data.

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?

An output schema exists, so return values needn't be described, and the annotations carry the safety story. Still, an agent is left without guidance on ordering, whether pagination requires iterating until a short page, or what strategy_id filtering does, which matters for a three-parameter list tool with sparse schema coverage.

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

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

Schema description coverage is only 33%, so the description must carry weight: it documents offset and limit and even adds a max of 100 that the schema does not state, which is genuinely useful. However it silently omits the third parameter, strategy_id, whose semantics (strategy membership UUID) appear only in the schema, leaving a real 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?

States a specific verb ('List') and resource ('the authenticated user's saved screeners'), with a clarifying parenthetical of what a screener is (filter queries + schedule). The 'list' verb cleanly separates it from create_screener, update_screener, delete_screener and run_screener among 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?

Usage is only implied: an agent can infer this is the way to enumerate saved screeners, and the offset/limit args hint at paged browsing. There is no explicit when-to-use statement, no mention of using it to discover IDs before calling run_screener or update_screener, and no exclusions versus those siblings.

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

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

Annotations already establish that this is a safe read-only, non-destructive, non-open-world operation. The description adds useful context: results are scoped to the authenticated user, they omit full markdown, and writes are not possible through this path.

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 short and front-loaded: it states what is listed, what fields are included, and where to go for fuller data. The final sentence about strategy writes is slightly tangential for a list tool but still clarifies a boundary.

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

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

With an output schema, rich annotations, and full schema description coverage, the description is largely complete: it covers scope, fields, exclusions, and the main alternative. A minor gap remains around why a list tool accepts an optional strategy_id, but the structured schema addresses that parameter.

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

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

Schema description coverage is 100%, so the single optional strategy_id parameter is already documented in the schema. The description does not add any parameter-level meaning, which matches the baseline 3 when the schema carries the burden.

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 and resource: 'List the authenticated user's agent-rail strategies.' It also names representative fields and contrasts the result with get_strategy, so the agent can distinguish this tool from its sibling.

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

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

It explicitly says to use get_strategy when full markdown, settings, and links are needed, and it notes that strategy writes require the Terminal browser or agent. This gives clear routing guidance and a boundary for what this tool does not support.

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

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

Annotations already establish read-only and non-destructive behavior. The description adds ordering ('newest first') and content ('with version notes'), which are useful beyond the annotations, though it does not discuss pagination or empty results.

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 and compact: one sentence states what is listed and its ordering/content, followed by a narrowly scoped Args note. Every sentence 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?

For a single-parameter, read-only list tool with an output schema and clear annotations, the description is nearly complete. The only minor gap is no explicit note about pagination or empty result behavior, though the output schema likely covers return shape.

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

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

Schema coverage is 0%, so the description carries the burden for the single parameter. It identifies the value as a Strategy UUID and points to list_strategies as the source, adding meaningful semantics beyond the bare schema.

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

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

The description states a specific verb and resource: list saved generations for a strategy. It adds useful scope details (newest first, version notes), so an agent can distinguish this from get_strategy or list_strategies.

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 implies usage by saying versions are for a strategy and that strategy_id comes from list_strategies, but it does not explicitly compare against get_strategy or state when not to use this tool.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds the useful scope constraint that results are limited to the authenticated user's watchlists. It says nothing about ordering, pagination totals, or how symbols are nested in the response, but the output schema carries return structure.

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

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

The purpose sentence is front-loaded and the Args block is terse and scannable. It is appropriately sized for a simple paginated list tool.

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

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

An output schema exists, so return shape needn't be explained. For a three-parameter tool the description covers pagination adequately but leaves strategy_id unscoped and gives no ordering or result-count context.

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

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

Schema coverage is 33%, with only strategy_id documented in the schema. The description documents offset and limit and adds the 'max 100' cap that the schema omits, which is genuine value. However, it never mentions strategy_id, so one parameter relies entirely on its schema description.

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

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

States a specific verb and resource ('List the authenticated user's watchlists') and adds that symbols are included. It is distinguishable from create/update_watchlist by the verb, but it does not explicitly contrast with the other list_* 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?

There is no guidance on when to call this versus list_strategies or the create/update watchlist tools, nor any prerequisites. An agent must infer usage from the name alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the mutation and safety profile are covered for free. The description adds only that the target is a parent folder or library root. It does not disclose permission requirements, what happens to nested child folders or items, or whether the move can create cycles.

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 summary is front-loaded in a single sentence and the Args block is compact and scannable. The docstring formatting is slightly redundant with the schema, but nothing is padded or wasted.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. For a two-field move operation the description covers the input semantics and root-targeting case; the only residual gap is the orphaned strategy_id parameter, which is a schema defect more than a description omission.

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 33%, so the schema leaves folder_id and parent_id undocumented and the description compensates by defining both, including the omit-or-null convention for library root. However, the third parameter strategy_id is wholly unaddressed by the description, and its schema text ('the card this call writes keeps that id') reads as copied from an unrelated tool, leaving that parameter semantically murky for a folder move.

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 gives a specific verb and resource: 'Move a library folder under a different parent (or to root).' This clearly separates it from sibling mutations like move_library_item, rename_library_folder, and delete_library_folder. It does not explicitly name those siblings, but the verb-plus-resource pairing 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 parenthetical '(or to root)' implies the two usage modes: reparenting versus resetting to the library root, and the Args section reinforces that parent_id may be omitted. However, it gives no guidance on when to choose move_library_folder instead of delete/create or move_library_item, and it states no prerequisites or exclusions.

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

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

Annotations already declare it as a non-read-only, non-destructive, closed-world mutation. The description adds a genuinely useful behavioral detail — passing null/omitting folder_id relocates to the library root — which the schema's default=null does not make obvious on its own. It says nothing about permission requirements, what happens if the item is already in the target folder, or 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 operative sentence is first and the parameter notes are brief. The Google-style 'Args:' block is slightly noisy boilerplate but each line carries real information and nothing is padded.

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

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

Output schema exists, so return values needn't be explained, and the core move semantics are covered. Still, for a mutation tool an agent would benefit from knowing about permission requirements or whether the destination folder must already exist in the same library.

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 low (33%), and the description compensates by explaining both item_id and folder_id, including the null-means-root semantics that the schema only encodes as a bare default. The third parameter, strategy_id, is not mentioned in the description, but the schema itself documents it thoroughly, so the coverage gap is effectively closed.

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 ('Move a library document') plus the destination concept (folder or root), which is enough to distinguish it from most siblings. It does not explicitly distinguish itself from the near-twin 'move_library_folder', leaving the document-vs-folder distinction to inference from the word 'document'.

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

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

No guidance on when to use this versus 'move_library_folder' or 'update_library_item', and no prerequisites (folder existence, ownership, same-library constraint). Usage is only implied by the name and the root-omission note.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description should add context beyond that. Instead it says nothing about permission requirements, whether the name must be unique within a parent, whether the rename is reversible, or what happens on conflict. The description contributes no behavioral detail beyond what annotations provide.

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

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

The one-line description is front-loaded and efficient, but the subsequent Args block duplicates schema information rather than adding meaning. This is not wastefully long, but it could be collapsed into the introductory sentence without any 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?

This is a mutation tool, and the absence of prerequisites, permission notes, or conflict behavior leaves meaningful gaps for an agent invoking a rename operation. Although an output schema exists and return values do not need to be explained, the description fails to clarify the optional strategy_id parameter or any mutation-specific behavior.

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 33%, since only the optional strategy_id parameter has a description in the schema. The description clarifes that folder_id is 'The folder UUID' and name is the 'New folder name', which maps to two of the three parameters, but it omits explanation of the optional strategy_id parameter that the schema documents separately. At 33% coverage, the description compensates for only part of the gap.

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

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

The description states a specific verb+resource: 'Rename a library folder.' This is unambiguous and separates it from sibling tools like move_library_folder, delete_library_folder, or create_library_folder. It stops short of explicitly naming those alternatives, but the verb itself is distinctive.

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?

There is no guidance on when to use this tool versus alternatives, no mention of prerequisites, and no note on how it differs from move_library_folder. The description only declares what the tool does, leaving the agent to infer the usage context.

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

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

Annotations only declare that this is a non-destructive write; the description adds the rate limit (5 per user per day), where the record surfaces (admin inbox), and the consequence of omitting ticker/section (no terminal URL for admins). It also clarifies that page_url is optional when the page is already a terminal.manawa.app link, which is side-effect-relevant context not present in annotations.

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

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

The governing rules are front-loaded in three tight sentences, then an Args block adds the per-parameter detail. There is mild duplication between the prose (ticker/section, page_url, block_id, item_ids) and the Args list, but the Args entries carry extra specifics, so little is wasted.

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

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

For an 8-parameter mutation tool this is complete: trigger conditions, rate limit, destination, parameter semantics, and prioritization (prefer block_id when tied to a page element) are all covered. An output schema exists, so return values need not be described.

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 only 13%, and the description compensates: it documents 7 of 8 parameters with meaning the schema lacks — the 10–2000 character bound on description, section examples (overview, financials, thesis, valuation), what block_id refers to (registry.ui_blocks id), and item_ids as provenance/store ids. Only strategy_id is left to the schema, where it is already documented.

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 ("Log a bug") plus the destination behavior — it lands in the same inbox as the terminal bug button — which no sibling tool touches. An agent can distinguish it from every other write tool in the sibling list without opening the schema.

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?

Gives an explicit trigger ("Use only when the user asks, or when you have confirmed a real data/UI error") and an explicit exclusion ("Do not file speculative bugs"). That is a genuine when/when-not rule with a stated evidence bar, not an implied one.

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses async behavior ('returns as soon as queued — do not poll'), quota consumption rules, and that re-running an unlocked ticker this month does not consume a grant. This is substantial behavioral context that annotations do not carry.

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

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

Front-loaded with the core action, then quota rules, then the async note, then args. Every sentence is informational. The quota tier listing is slightly verbose but earns its place by defining eligibility.

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 non-destructive mutation tool with an output schema (so return values needn't be explained), the description covers triggering, quota gating, idempotency, async semantics, and both key parameters. The remaining gap is minor: no explicit alternative-tool routing.

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 only 33% (only strategy_id is documented in the schema), but the description supplies the missing meaning for ticker (with an example) and force (when to use it, with a concrete failure scenario). Together the schema and description cover all three parameters well.

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 gives a specific verb and resource: 'Queue a full DeepDive suite for a stock.' It is unambiguous what the tool does and clearly distinct from generic analysis siblings. It does not explicitly name a sibling it competes with, but no other DeepDive tool exists, so differentiation is implicit.

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 explains when-not: 'Prepaid search credits cannot pay for this' and the quota tiers that gate usage. It also gives a specific condition for using force (wrong-instrument on-file content). It stops short of naming an alternative tool for overlapping needs, but the 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?

Annotations only declare the safety profile (readOnly=false, destructive=false, openWorld=false); the description goes further by disclosing that the call persists last_symbols, that the first seed sends no notifications, and that later runs notify joiners/leavers gated on a user setting. That notification side effect is exactly the kind of non-obvious behavior an agent needs, though the references to 'Settings Screener in & out' and 'Terminal Run now' are opaque UI jargon rather than precise semantics.

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

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

Very short and front-loaded: the action and its effects come in the first sentence, behavioral caveats second, args last. The semicolon-chained fragments ('persist last_symbols; return entered/exited') and the 'Args:' block duplicate structure rather than add prose, which keeps it tight but slightly telegraphic.

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?

An output schema exists, so return values need not be spelled out, and the two-parameter surface is small. The description covers the essential non-obvious behavior (state persistence, conditional notifications) but leaves the notification condition referenced only by an ambiguous settings label, which the agent cannot resolve on its own.

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 50%: strategy_id is fully documented in the schema, but screener_id has no schema description. The description compensates by specifying it is 'the screener UUID from list_screeners', which tells the agent both the format and the discovery path. The Args block is minimal but covers the undocumented parameter.

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 ('Re-run a saved screener') plus its two observable outcomes (persist last_symbols, return entered/exited). This clearly separates it from create_screener, update_screener, and list_screeners, which the agent can rule out without opening any schema.

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 screener_id arg note ('UUID from list_screeners') implies a screener must already exist, so the agent can infer the discovery-then-run flow. However, there is no explicit when-to-use vs when-not guidance, no mention of update_screener for changing criteria, and no statement about prerequisites such as whether the screener must have been seeded.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the meaningful scoping fact that only the authenticated user's library is searched, but says nothing about ranking, pagination beyond the limit cap, or result ordering — and an output schema exists so return-shape detail is rightly omitted.

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 core capability is stated in a single front-loaded sentence with no waste. The trailing docstring-style "Args:" block is slightly redundant as a format but each line carries real content, notably the limit cap.

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 search with annotations and an output schema, the essentials are present, but an agent still cannot tell how this differs from list_library_items or finance_search, whether results are ranked or paginated beyond the limit, or what role strategy_id plays in a search call. Adequate, not complete.

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

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

Schema coverage is 33%: only strategy_id carries a schema description, and the description usefully compensates for limit by disclosing the cap of 50 that the schema does not state. The query definition ("Search terms") is a bare restatement with no syntax, matching, or phrase behavior, and strategy_id's effect on this call is left entirely to the schema.

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

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

"Full-text search across the authenticated user's library documents" gives a specific verb (full-text search) and a specific resource (library documents), which separates it from list_library_items / get_library_item in the sibling set. It stops short of explicitly naming those siblings as alternatives, so the differentiation is inferable rather than stated.

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?

There is no when-to-use / when-not guidance and no named alternative among the many library and search siblings (list_library_items, finance_search, run_deepdive). The only scoping signal is that the search is confined to the authenticated user's own library.

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?

Goes well beyond the annotations by disclosing that the write is accepted immediately but the readable entry is generated asynchronously at end of day, and that same-day resubmissions are retained as separate drafts (a real duplication hazard). It also warns that the returned draft id is not a list_journal / get_journal_entry id until generation completes — exactly the kind of ID-mismatch trap an agent would otherwise fall into.

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 core lifecycle and ID caveat are front-loaded in the first three sentences, which is the right ordering. The trailing 'Args:' block partially restates the schema, but it carries genuine format information (YYYY-MM-DD), so little is wasted.

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

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

An output schema exists, so return values need no explanation, yet the description supplies the one thing the schema cannot: the temporal meaning of the returned draft id. Complete for a low-complexity, 3-parameter write tool; the only omission is any mention of the optional strategy_id.

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 low (33%), and the description compensates for the two undocumented required params by specifying entry_date's YYYY-MM-DD format and identifying content as the draft text. It says nothing about the optional strategy_id, though the schema itself documents that parameter adequately, so the gap is narrow.

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 ('Submit a journal draft for a day') and immediately clarifies the object's lifecycle relative to the sibling read tools (list_journal, get_journal_entry). An agent can tell this apart from listing or fetching journal entries without opening the schema.

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?

Explains the downstream flow clearly: submit now, the readable entry appears in list_journal at end of day, so an agent knows when to call this versus when to read. It does not state explicit exclusions or name a competing write alternative, but no such sibling exists, and the guidance is otherwise concrete.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, so the description adds real value by clarifying that the operation only appends a tag and leaves the strategy playbook untouched. It does not cover failure modes (e.g. invalid strategy_id) or whether repeat tagging is idempotent, so it falls short of 5.

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

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

Front-loaded with the core action, then prerequisite, then a structured Args block. Slight redundancy between the title and the first sentence, and the enum lists are run together in prose rather than as a compact list, but nothing is wasted.

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

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

With an output schema present and annotations covering the safety profile, the description supplies the missing prerequisite, scope, and enum semantics. It would be complete with a note on what happens when strategy_id is invalid or when the same activity is tagged twice.

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 declares no enums, yet the description documents all five parameters: strategy_id's source, title's expected brevity, kind's full value set plus default, tickers, and tool's value set plus default. This is exactly the compensation the low coverage 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?

The description opens with a specific verb and resource: 'Mark one action as belonging to a strategy already on this account.' It also scopes the write ('This only writes the activity tag'), which cleanly separates it from siblings like get_strategy, list_strategies, and submit_journal_draft.

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

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

It gives an explicit prerequisite and ordering: 'Call list_strategies first and pass that id.' It also states a boundary ('The playbook stays read-only'), telling the agent what this does not touch. No alternative tool is named, but there is no competing sibling for this operation.

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 only say readOnlyHint=false, destructiveHint=false, openWorldHint=false. The description adds real behavioral context: content edits create a new version, content must be markdown unless the document is already text/html, and the document type is immutable. It omits what happens on an unknown item_id or a type mismatch, so not a 5.

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

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

Front-loaded with the action and its most consequential side effect (versioning), then constraints, then a compact Args list. The Args block partially duplicates the schema property names, but with low schema coverage that repetition 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?

An output schema exists, so return values need no explanation, and the description covers the mutation's key side effect and content-format rules. Gaps remain around failure modes and whether an empty string clears a field, but nothing critical to making a correct call 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 description coverage is only 25% (strategy_id is the sole documented parameter), so the description must compensate. Its Args block covers item_id, title, and content and adds format semantics for content, which is genuinely useful, but item_id is described only as 'The item UUID' with no hint about where to obtain it, and strategy_id is left entirely to the schema.

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

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

States a specific verb and resource (update a library document's title and/or content) and names the editable fields. The versioning note ('content edits create a new version') distinguishes it behaviorally from a plain rename, though it never names the sibling to use for creation or renaming.

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?

Usage is implied: this edits an existing item, so create_library_item / delete_library_item are the obvious counterparts, and 'optional' on both fields signals partial updates. But there is no explicit when-to-use/when-not statement, no prerequisite that the item must already exist, and no mention of list_library_item_versions for inspecting 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?

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. Beyond that, the description discloses genuinely valuable behavior: this is a partial-update operation (only changed fields need to be sent) and it surfaces three non-obvious defaults (approval request on, strategy run start off, finish on). The main gap is that defaults are given for only 3 of 16 fields, leaving the agent to guess whether an omitted field reverts to a default or stays untouched.

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 invocation rule front-loaded, and no restating of the name or title. The trailing defaults fragment is slightly telegraphic and would read better as a single sentence, but nothing here is 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?

An output schema exists, so return values need not be explained, but for a 16-parameter mutation tool with near-zero schema documentation the description leaves major questions open: the scope of a strategy-scoped versus global update, whether null differs from omission, and what the defaults are for the other thirteen flags. That is thin for a tool of this surface area.

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 6% – only strategy_id carries any description, and even that one is boilerplate. The description names just three of the sixteen parameters and explains the boolean typing generically; it never clarifies what triggers alert, journal, deepdive, screener, price-move, or acceleration notifications, nor whether email_notifications is a channel toggle or a master switch. With coverage this low, the description needed to compensate and does not.

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 ("Update notification preferences") that an agent can immediately map to the sibling read tool get_notification_settings. It does not explicitly name that sibling or state the distinction, but the operation itself is unambiguous for a 16-field boolean settings object.

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?

"Pass only the fields to change" is a useful invocation rule that tells the agent to send a partial payload rather than a full settings object. However, there is no guidance on when to use this versus get_notification_settings, no mention that strategy_id scopes settings to a specific strategy versus global preferences, and no prerequisites or permission notes.

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

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

Annotations already declare that the tool is mutating, non-destructive, and closed-world, so the description does not need to repeat safety basics. It adds useful behavior beyond annotations, including the Pro requirement for weekly schedules, the enter/exit notification toggle, and that last_symbols refreshes the baseline from the live table.

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 uses a compact Args section for parameter semantics. Every sentence adds useful information without 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?

With annotations covering safety and an output schema covering return values, the description supplies the key remaining context for a 7-parameter mutation tool. Its main gap is the omitted strategy_id, though the schema describes that parameter, and it lacks explicit when-not-to-use guidance.

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 only 14%, so the description must compensate, and it does for six of seven parameters: it explains screener_id source, name, query, schedule values, notify_on_change, and last_symbols. It omits strategy_id, but that parameter is documented in the schema itself.

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: updating a saved screener's name, query, schedule, or baseline symbols. This clearly distinguishes it from sibling tools such as create_screener, delete_screener, list_screeners, and run_screener.

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 by saying it updates a saved screener and notes that screener_id comes from list_screeners, but it does not explicitly say when to use this tool versus create_screener, delete_screener, or run_screener. The only explicit constraint is that weekly schedules require Pro.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, and openWorldHint=false, so the description only needs to add mutation-specific context. It mentions optional fields but does not disclose whether symbols replaces the entire list or merges, whether omitted fields are left unchanged, or what happens when the watchlist_id is invalid.

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 short and front-loaded with the core operation. The Args block is somewhat redundant with the schema, but it is organized and does not waste much space.

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

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

Given a mutation tool with four parameters and an output schema, the description should clarify update semantics and all parameters. It leaves out strategy_id and does not explain whether symbols replaces or appends, making it incomplete for safe invocation.

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

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

The description documents watchlist_id, name, and symbols, giving the UUID meaning and calling out optionality. However, it omits strategy_id entirely, and schema description coverage is only 25%; the description does little to compensate beyond restating basic parameter roles.

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