Manawa Terminal

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

The description adds behavioral detail beyond the annotations by explaining that symbol aliases 'CASH' and blank are normalized to '$CASH', and that qty represents cash amount for deposits/withdrawals. It also specifies the date format (YYYY-MM-DD). This provides useful context that annotations don't convey, though it doesn't mention side effects like portfolio balance updates.

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

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

The description is compact and front-loaded with the main purpose, followed by a structured Args block. Each line adds necessary information, with no filler or redundancy. It strikes a good balance between completeness and brevity.

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

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

The description is complete for a 6-parameter tool: it covers all required arguments, provides examples and normalization rules, and clarifies the interpretation of qty across transaction types. An output schema exists, so return-value details are not needed. It lacks only minor preconditions (e.g., portfolio existence), which are likely evident.

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

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

With 0% schema description coverage, the description fully compensates by listing all 6 parameters and their meanings. It explains the special symbol handling for cash transactions and distinguishes qty semantics by side (shares vs cash amount). This is exemplary parameter documentation.

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

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

The description opens with a specific verb and resource: 'Add a buy, sell, deposit, or withdrawal transaction to a portfolio.' It clearly identifies the action and object, and the transaction types distinguish it from sibling tools that create other resources (e.g., create_portfolio, create_watchlist).

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 doesn't explicitly state when not to use it or name alternatives, but the description provides clear context: it's for adding any of four transaction types to a portfolio. The parameter guidance (e.g., cash handling) reinforces the intended use case. Since there is no competing sibling tool for adding transactions, this is sufficient.

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

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

The description goes beyond the minimal annotations by specifying conditional requirements for different alert types (direction/threshold for price alerts, event_types for event alerts) and enumerating all accepted event types. This gives concrete behavioral expectations that annotations do not 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 description is a well-structured docstring with a clear one-line summary followed by a compact parameter list. Each entry is concise, and the whole is scannable without unnecessary prose.

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

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

For a tool with six parameters and conditional logic, the description is thorough: it covers all parameters, their types, required-ness based on alert_type, and the full set of event types. It is complete enough for an agent to invoke the tool correctly without further clarification.

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 zero schema description coverage, the description fully compensates by explaining each parameter's meaning, conditions, and even providing an example for symbol. It also lists all valid event_types, which the schema does not enumerate.

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 the specific verb 'Create' and clearly identifies the resource as a 'price or event alert', which distinguishes it from sibling tools like list_alerts and delete_alert. The expanded scope beyond the title's 'price alert' is still specific and meaningful.

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

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

The description clearly implies when to use this tool: to create a new price or event alert. It does not explicitly name alternatives or exclusions, but the unique purpose and sibling context make the use case obvious, though not as explicit as it could be.

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

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

With annotations already declaring readOnlyHint=false and destructiveHint=false, the description adds useful behavioral context by explaining that the folder can be nested under a parent or created as a root folder. This goes beyond the schema and clarifies the outcome of omitting parent_id, though it does not mention permissions or 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 exceptionally concise: a one-sentence purpose statement followed by a compact args list. Every word earns its place, and the most critical information (root vs nested) is front-loaded. No fluff or redundancy.

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

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

For a simple create operation with only two parameters and an output schema present, the description is complete. It covers the purpose, parameter semantics, and the critical edge case of root vs nested folders. The tool's low complexity means no further context is needed.

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

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

Despite schema description coverage being 0%, the description compensates by explaining both parameters: 'name' as the folder name and 'parent_id' as a parent folder UUID, explicitly stating that omitting it creates a root folder. This adds significant meaning beyond the raw schema.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Create a library folder'. It also distinguishes from sibling tools by mentioning the 'library' scope and optional nesting, which differentiates it from create_library_item or create_portfolio.

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

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

The description provides context on how to use the parent_id parameter ('omit for a root folder'), which implies when to use it, but it does not explicitly discuss when to use this tool versus alternatives. There is no exclusionary guidance or mention of sibling 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 indicate readOnlyHint=false and destructiveHint=false, so the description is not responsible for basic safety disclosure. It adds useful behavioral detail like 'HTML is stored as source' and optional folder placement, giving the agent more context beyond annotations.

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

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

The description is efficient: a single opening sentence and a compact Args block that lists each parameter with meaningful detail. No filler or redundant statements.

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

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

The description covers all parameters, notes defaults and optionality, and there is an output schema (per context signals) so return values need not be explained. It could mention error conditions or uniqueness constraints, but these are not critical for a basic create operation.

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

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

With 0% schema description coverage, the description fully compensates by explaining each parameter: title, content (with content_type interaction), folder_id (optional, root default), and content_type (default and format). This is rich, actionable semantic detail that the schema alone lacks.

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

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

The description states a clear verb ('create') and resource ('markdown or HTML document in the research library'), which distinguishes it from folder creation and other library operations. The mention of content types further clarifies the exact scope.

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

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

No explicit when-to-use or alternatives are mentioned. While the purpose is clear, the description does not guide the agent on when to choose this over create_library_folder or update_library_item, relying on inference from the name and sibling context.

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

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

Annotations already indicate this is a mutation (readOnlyHint=false). The description only restates the schema parameters (name, currency) without adding any extra behavioral details such as idempotency, duplicate handling, or required permissions. It adds no information beyond what annotations and schema 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 description is extremely concise, leading with a clear purpose sentence and then listing the two parameters. Every sentence earns its place, with no filler or repetition.

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

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

For a simple two-parameter create tool with an output schema present, the description sufficiently covers the required inputs. It does not need to explain return values since the output schema exists. Minor omissions like duplicate name behavior are not essential for basic invocation.

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

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

The schema has zero description coverage for its parameters. The description compensates fully by explaining 'name' as the portfolio name and 'currency' as the base currency with a default of USD. This provides clear meaning beyond the raw schema definitions.

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

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

The description clearly states 'Create a portfolio' with a specific verb and resource. This distinguishes it from sibling tools like create_watchlist or create_alert by targeting the portfolio entity.

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 context is clear: use this tool to create a new portfolio. It does not explicitly exclude any scenarios or mention alternatives, but the purpose is evident among the sibling tools. No exclusion is necessary for such a straightforward create 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?

The description only repeats the basic creation action and parameter names, adding no behavioral details such as idempotency, duplicate handling, permissions, or return value behavior. Annotations indicate readOnlyHint=false and destructiveHint=false, but the description offers no extra transparency beyond that minimal signal.

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

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

The description is extremely concise, with a direct opening sentence and minimal parameter explanations. No fluff or repetition; every line serves a clear purpose and is front-loaded with the core action.

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 with two straightforward parameters and an output schema exists, so the description covers the essentials. However, it omits behavioral context like what happens on duplicate names or whether the action is reversible, and lacks usage guidance, leaving it adequate but incomplete for an AI agent.

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

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

The schema has no descriptions for parameters, so the description's Args section adds some value. 'symbols' is clarified with an example (['AAPL', 'MSFT']), aiding understanding, while 'name' is tautological ('Watchlist name'). This partially compensates for the 0% schema description coverage but is not deeply informative.

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

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

The description clearly states the tool creates a watchlist with a given name and ticker symbols, using a specific verb and resource. It distinguishes from siblings like update_watchlist by focusing on the creation action, though it does not explicitly contrast with 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?

The description provides no guidance on when to use this tool versus alternatives such as update_watchlist or list_watchlists. It does not mention scenarios, prerequisites, or exclusions, leaving the agent without context for choosing 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?

The annotations already declare destructiveHint=true and readOnlyHint=false, and the description is consistent. It adds no extra behavioral context beyond 'delete by ID', but the safety profile is already covered.

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

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

The description is extremely concise, front-loaded, and contains no unnecessary words. It earns every sentence.

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 delete operation with annotations and an output schema, the description covers the core action. However, it omits potential caveats like irreversibility or ownership requirements, though these are partially implied by the destructiveHint.

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

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

With 0% schema description coverage, the description partially compensates by specifying alert_id as a UUID. This adds meaning beyond the bare string type, though it lacks additional details.

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

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

The description clearly states the tool deletes an alert by ID, using a specific verb and resource. It distinguishes itself from sibling tools like create_alert and list_alerts.

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 is given on when to use this tool versus alternatives, such as requiring an existing alert_id or confirming permanence. The description only states what it does without context for usage.

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

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

The description adds the key behavioral detail that the folder's contents are also deleted, which goes beyond the annotations' mere destructiveHint flag. It clarifies the cascading nature of the deletion, though it doesn't mention irreversibility (already implied by 'delete').

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 a single imperative sentence followed by a minimal args list. It is front-loaded and has no filler, earning a high score.

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

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

For a simple delete operation, the description covers the tool's purpose and parameter. The output schema handles return values, and annotations convey the destructive nature. However, it could mention error conditions or necessary permissions, but these are likely assumed for a straightforward delete.

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

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

The schema only defines folder_id as a required string with no description. The description's Args block states 'The folder UUID', adding format information (UUID) that the schema lacks, which is helpful but minimal; it doesn't explain how to obtain the ID or any validation rules.

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 'Delete a library folder and everything inside it' with a clear verb and resource, and the 'everything inside it' distinguishes it from delete_library_item and other folder operations. This provides specific scope.

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

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

No explicit guidance on when to use this tool over alternatives like move_library_folder or rename_library_folder is provided. The context only implies that deletion is intended for discarding a folder and its contents, but no exclusions or alternatives are mentioned.

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

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

The annotation already includes destructiveHint:true, so the destructive nature is known. The description adds valuable context that the deletion removes all stored versions, which is a behavioral nuance beyond the annotation. It doesn't mention irreversibility or permissions, but the annotation covers the core destructive trait.

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 concise and front-loaded. The main statement is one sentence, followed by a minimal Args section. Every word contributes value with no redundancy.

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

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

For a single-parameter tool with an output schema and clear annotations, the description fully covers purpose, effect, and parameter semantics. The output schema handles return values, so no additional return info is needed. It is complete for its complexity level.

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

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

The schema provides no description for item_id, so the description's Args section ('The item UUID') fills the gap. This is sufficient to understand the parameter format and purpose, though it is minimal.

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

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

The description clearly states the tool's function with a specific verb ('Delete'), a specific resource ('library document'), and important scope ('all of its stored versions'). This distinguishes it from sibling delete tools like delete_alert and delete_library_folder.

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 tool's purpose is evident from the name and description, so an agent can infer when to use it. However, it does not explicitly mention alternative tools or when not to use it. Since there is likely no alternative for deleting a library item, this is acceptable but not top-tier.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real behavioral context beyond that: the exclusive-mode semantics, that it returns a rendered answer/widget rather than raw data, and the interplay between focus, source and section. It stops short of describing result shape 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?

Front-loaded with the core purpose, but the Args block balloons into a long, partially redundant wall of routing rules (repeated "Do not send those to X" instructions). Most rules are functional given the absence of enums, but the phrasing repeats and could be tightened substantially.

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 no output schema, the description should explain the return; it does so minimally ("answer with an inline widget"). For a five-parameter, mode-driven tool the mode/section matrix is thoroughly covered, though the response format and mode-precedence edge cases are only lightly touched.

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

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

Schema description coverage is 0%, so the description must carry the full burden, and it does: it defines query, symbols, focus (ai|raw|auto|catalog), source examples, and an extensive section vocabulary with disambiguation rules. This is a case where prose fully compensates for an undocumented 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 ("Search financial data and return an answer with an inline widget") and enumerates the covered domains (stocks, macro, forex, crypto, commodities, earnings, technicals). It also routes to siblings (list_watchlists/list_portfolios) and distinguishes its Deep Dive modes, so an agent can tell it apart from the rest of the toolset.

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 explicit when-to-use guidance: screening a named watchlist requires calling list_watchlists/list_portfolios first, and it spells out the exclusive focus modes (ai/raw/catalog) with their conditions. The negative routing rules (buzz must be section=buzz, not news/catalysts; acceleration not movers; heatmap not sector treemap) are unusually explicit about what NOT to do.

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. Description adds behavioral context: draft IDs are not readable until end-of-day, and valid IDs come from list_journal, which clarifies timing constraints beyond the 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?

Brief, front-loaded purpose, followed by essential usage and parameter details. No wasted words; Args block cleanly documents the single parameter.

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

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

For a one-parameter read operation with output schema present, the description covers purpose, eligibility of IDs, and parameter format. Complete and self-sufficient.

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 only defines entry_id as a string with no description. The description's Args section explains entry_id is a journal entry id from list_journal, accepts integer or UUID, providing critical meaning at 0% schema coverage.

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

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

Description clearly states 'Get a full generated journal entry by ID from list_journal', specifying verb, resource, and scope. It distinguishes from sibling tools like list_journal 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?

Explicitly explains when to use: after end-of-day generation, using list_journal for valid entry IDs, and warns against using draft IDs from submit_journal_draft. This provides clear context and 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 and destructiveHint=false, and the description does not contradict them. The description adds valuable context beyond annotations by specifying that content can be markdown, raw HTML, or a signed PDF URL depending on content_type. However, it does not disclose error behavior for invalid IDs or how versioning interacts with the returned content.

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

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

The description is compact and front-loaded: purpose first, content-type behavior second, and a minimal args line. Every sentence earns its place, and the UUID clarification in the args block justifies its small redundancy with 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 one-parameter, read-only tool with an output schema and safety annotations, the description covers the key complexity: the conditional content representations. The main gaps are where to source item_id and behavior for nonexistent items, which are minor given the tool's simplicity and the presence of an output schema.

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

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

Schema coverage is 0%, so the description must compensate. It does add meaning by stating item_id is 'The item UUID,' which is more specific than the bare string type in the schema. However, this is minimal compensation — it does not clarify where the UUID comes from (e.g., list_library_items) or expected format, leaving the agent to guess.

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

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

The description uses a specific verb-resource pair ('Get a library document's metadata and content') and elaborates on what is returned. It is distinguishable from siblings like list_library_items (plural listing) and get_journal_entry (different resource type), though it never names a sibling explicitly, which keeps it just shy 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 guidance on when to choose this tool over alternatives such as list_library_items, list_library_item_versions, or search_library. No when-to-use, when-not-to-use, or prerequisite conditions are stated, so the agent must infer selection purely from the tool name and context.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavior: notifications are unread-only and the upstream caps results at 50, which materially affects how an agent should page.

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 purpose sentence followed by a compact Args block; every line carries information. Slightly verbose by restating schema defaults, though that is defensible given 0% schema coverage.

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

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

An output schema exists, so return values need no explanation. With pagination documented, the unread cap disclosed, and the safety profile in annotations, an agent has everything needed to call this correctly.

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

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

Schema coverage is 0%, so the description must carry the load, and it does: offset is defined as a skip count, limit as page size with default 50 and max 100. The only omission is behavior when offset exceeds the 50-unread upstream cap.

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 with a meaningful qualifier: "recent triggered alert notifications." The word "triggered" implicitly separates it from list_alerts (alert definitions), but no sibling is named explicitly, so it falls 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 statement about when to use this tool versus list_alerts or any other sibling, and no prerequisites or exclusions are given. The only contextual cue is the unread cap, which is behavioral rather than usage guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description ('Get portfolio statistics') is consistent with those. The description adds the data categories (returns, allocation, risk) but does not disclose additional behaviors such as response formatting, pagination, or required permissions. Given the strong annotations, this is acceptable but not exceptional.

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 concise and well-structured. It opens with a clear purpose statement, then lists the single argument in a standard Args block. Every part earns its place, with no redundant or filler content.

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

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

The tool is simple (one parameter) and has an output schema, so the description does not need to detail return values. It conveys the core purpose and parameter semantics adequately. No critical information appears missing for an agent to decide whether and how to invoke it.

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

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

The schema only provides the parameter name and type, but the description explicitly states 'portfolio_id: The portfolio UUID', clarifying that the value is a UUID. This adds meaningful semantic clarity over the bare schema, effectively compensating for the 0% schema description coverage.

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

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

The description clearly states the verb 'Get' and the resource 'portfolio performance statistics' with specific dimensions (returns, allocation, risk). This distinguishes it from sibling tools like get_positions or list_portfolios, making its purpose unambiguous.

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

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

The description implies usage context: it is for retrieving performance statistics for a specific portfolio. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any exclusions or prerequisites. The user must infer usage from the name and description.

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

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

The annotations already declare readOnlyHint=true and destructiveHint=false, so the description's read-only nature adds no new safety info. The description does add that it returns 'current holdings' and the specific value fields, which is useful but not rich behavioral context like pagination, auth requirements, or data freshness.

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 a single concise sentence front-loaded with the action, followed by a minimal args line. No wasted words; every part 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 simple single-parameter read-only tool with an output schema and safety annotations, the description is largely complete. It lacks usage guidance and any caveats, but the core purpose and parameter meaning are clear. Slight deduction for not mentioning when to prefer this over get_portfolio_statistics.

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 0%, the description compensates by explaining portfolio_id as 'The portfolio UUID', providing format and semantic meaning beyond the schema's bare 'Portfolio Id' title. This is sufficient for a single parameter, though it could explicitly state that it's the portfolio whose positions are retrieved.

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: 'Get current holdings' with the exact fields included (quantity, cost basis, market value, unrealized P&L). This distinguishes it from siblings like list_portfolios (which lists portfolios) and get_portfolio_statistics (which likely returns performance metrics).

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. It does not mention exclusions, prerequisites, or point to sibling tools for related tasks. The description only states what it does, leaving the agent to infer usage context.

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

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

Annotations already establish readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds contextual value by revealing that only ACTIVE alerts are returned and that results are scoped to the authenticated user, but says nothing about ordering, pagination totals, or rate 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 purpose is front-loaded in one sentence and the parameter notes are terse and free of filler. The trailing arg-list formatting is functional if slightly mechanical.

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 not be described, and pagination parameters are documented with defaults and caps. Nothing essential to invoking the tool correctly appears to be missing, though a note on ordering would round it out.

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 parameter burden and does so adequately: it explains offset ('skip this many alerts'), limit ('page size'), and adds non-obvious constraints (defaults of 0 and 50, plus a max of 100) that the bare schema does not convey.

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 active price and event alerts') and adds a meaningful scope qualifier ('active') plus principal scoping ('for the authenticated user'). The 'list' verb separates it cleanly from sibling create_alert/delete_alert, though no sibling is named explicitly.

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 guidance, no mention of the sibling tools that create or delete alerts, and no stated conditions or alternatives. The agent must infer usage from the verb 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 cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description still adds meaningful behavioral context beyond annotations: the generation-run lifecycle gating data visibility, draft exclusion, and the upstream retention limit of at most 90 days.

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 purpose, then the behavioral constraints, then the parameter list in a scannable Args block. Every sentence contributes, with only slight redundancy between the ordering note and the lifecycle note.

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 unnecessary, and the description is complete enough to call correctly: it covers paging params, ordering, visibility lifecycle, draft exclusion, and retention limits.

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 parameter documentation, and it does: offset (skip N, default 0) and limit (page size, default 50, max 100). It also adds a non-obvious upstream constraint (at most 90 days) that the schema does not encode. Minor gap: no guidance on page-size tradeoffs, but semantics are otherwise complete.

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 (generated daily research journal entries) plus ordering (most recent first). It also distinguishes itself from siblings by noting that drafts from submit_journal_draft are not listed, so an agent can tell it apart from submit_journal_draft and get_journal_entry without opening other schemas.

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

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

Clearly explains the context in which entries become visible (only after the automatic end-of-day generation run) and warns that drafts are excluded until then. It does not, however, explicitly route the agent to an alternative (e.g., get_journal_entry for a single entry), so it is strong on context but lacks explicit when-not/alternative guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds that results are scoped to the authenticated user's library, which is useful behavioral context, but it says nothing about ordering, total counts, or what happens past the final page.

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 is front-loaded in a single sentence, followed by a compact Args block with no filler. The docstring-style 'Args:' formatting is slightly mechanical but 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?

An output schema exists, so return shape need not be described. For a simple two-parameter paginated list with read-only annotations, the description covers scope and both parameters adequately, though it omits any note on ordering or how to detect the last page.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning, and it does: offset is explained as 'skip this many folders' and limit as page size with a max of 100, a constraint absent from the schema. It is not exhaustive about interplay between the two, but it meaningfully compensates for the undocumented 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 folders') and scopes it to the authenticated user's research library, which is enough to distinguish it from mutation siblings like create_library_folder or delete_library_folder. It does not explicitly call out its relationship to list_library_items or search_library, but the noun (folders) is clear enough on its own.

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 (e.g., search_library, list_library_items) and no stated preconditions or exclusions. The reader must infer usage purely from the name and one-line purpose.

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 pagination behavior (offset/limit defaults, max 100), which is useful context beyond annotations, but says nothing about ordering, total counts, or response 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?

Front-loaded one-sentence purpose followed by a compact Args block. Every line is functional; the only minor issue is the slightly redundant restatement of defaults 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 read-only list tool with an output schema, the description covers purpose, scope, and all parameters including an undocumented max limit. Nothing critical is missing, though ordering/pagination semantics could go further.

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

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

Schema description coverage is 0%, so the description must carry the load — and it does: it names all three parameters with meaning, defaults, and the max limit of 100, which is not in the schema. This adds real value over 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?

States a specific verb (List) and resource (documents in a library folder), and clarifies scope (root if no folder given). This distinguishes it from search_library and list_library_item_versions by being a browse/list operation over a folder hierarchy.

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?

Implies usage through the folder_id semantics (omit for root), giving context for the no-filter case. But it doesn't explicitly contrast with siblings like search_library or list_library_item_versions, so an agent must infer when to pick this over search.

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, covering the safety profile. The description adds 'newest first' ordering, which is a useful behavioral trait beyond the annotations. It does not mention pagination or limits, but for a simple read-only operation this is acceptable.

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

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

The description is highly concise, consisting of one sentence stating the purpose and an Args list. Every word earns its place, and the key information is front-loaded.

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

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

For a single-parameter, read-only tool with an output schema available, the description covers the essential purpose, ordering, and parameter format. It does not describe return values, but the output schema handles that responsibility.

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 defines item_id as 'The item UUID', which adds format meaning beyond the schema's generic string type. With only one parameter, this sufficiently compensates for the 0% schema description coverage.

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

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

The description clearly states the tool lists version history for a library document, with a specific ordering (newest first). This distinguishes it from sibling tools like list_library_items (which lists all items) and get_library_item (which retrieves a single 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?

The description implies usage (retrieve version history for a specific library item) but does not explicitly state when to choose it over alternatives or exclude cases where it is not appropriate. There is no mention of when not to use it, such as needing current content rather than 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=true and destructiveHint=false, so safety is covered. The description adds pagination context (defaults and max) but says nothing about ordering, total counts, or result shape. With annotations carrying the safety profile, this is an adequate but not rich 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?

Purpose is front-loaded in a single clear sentence, and the args block is compact. The 'Args:' layout slightly duplicates the schema, 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?

An output schema exists, so return values need not be explained. Pagination is documented, safety is covered by annotations, and the tool is simple (2 optional params). Sufficient for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden and does so well: it documents both offset ('skip this many') and limit ('page size, default 50, max 100'), including the max=100 cap that appears nowhere in the schema. This meaningfully exceeds the bare property names.

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

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

States a specific verb ('List') and resource ('portfolios') and scopes it to 'the authenticated user's,' which distinguishes it from siblings like create_portfolio or get_portfolio_statistics. Clear but does not explicitly name an alternative for disambiguation.

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, when-not-to-use, or alternative routing is provided. It never distinguishes itself from get_portfolio_statistics or get_positions, leaving the agent to infer usage from the verb 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=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that results are scoped to the authenticated user and implies paging via offset/limit, but says nothing about ordering, empty results, or rate limits beyond that.

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 and the parameter notes are compact with no filler. The Args block is slightly docstring-ish but every line 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 two-parameter read tool with an output schema already describing return values, the description covers scope, pagination, and defaults adequately. Only ordering/empty-result behavior is unaddressed, which is minor here.

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 load: it documents both parameters, their meaning ('Skip this many lists', 'Page size'), and their defaults, and adds the max of 100 that the schema does not contain. This is meaningful added value over the bare integer properties.

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 ... watchlists and their symbols') and scopes it to the authenticated user, which distinguishes it from sibling listers like list_portfolios or list_alerts by resource. It does not explicitly name alternatives, but the resource is unambiguous.

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

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

The description gives no when-to-use context, no prerequisites, and never mentions the sibling tools (create_watchlist, update_watchlist) or when this list is preferable to another. Usage is only inferable from the name and purpose.

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

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

Annotations already mark the tool as read-only and non-destructive. The description adds valuable behavior beyond that: admin-only restriction, empty options meaning skip the item, inclusion of already-rendered images for cache reuse, and status limited to live/draft in catalog mode. No contradiction with annotations.

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

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

The description is compact and front-loaded, opening with the admin-only and mode distinction before moving to per-parameter guidance. Every sentence adds useful information, and the Args section is scannable.

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

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

Given the tool's moderate complexity, five optional parameters, and existing output schema, the description covers the key operational context: access control, item vs. catalog modes, parameter semantics, cache reuse, and skip behavior. Nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 0%, so the description carries the full burden, and it documents all five parameters meaningfully. It explains content_id's expected gc:{id} or rd:{uuid} formats, labels section/language/format as catalog filters, restricts status to live or draft, and adds the 'empty options means skip' behavior.

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 the tool serves live formats for one inbox item or the catalog, clearly identifying its resource and scope. It distinguishes two modes (item vs. catalog), which helps differentiate its purpose, though it does not name a specific sibling alternative or use an explicit verb like 'get' or 'list'.

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

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

It gives actionable usage context: admin-only access, passing content_id from marketing_inbox for a specific item, and using catalog filters without content_id. It conveys when to use each mode but does not explicitly contrast with sibling tools like marketing_render or marketing_inbox, so no exclusions or alternatives are named.

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

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

Beyond the readOnlyHint and destructiveHint annotations, the description discloses that the tool is admin-only, returns already-generated images, and connects to a worker poll concept. It also signals a follow-up workflow with marketing_graphics, which is valuable behavioral 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 description is tightly packed: purpose, access restriction, filter usage, sibling-tool transition, and reusable output hints all fit into a few lines. The Args block is clearly formatted and the most important operational guidance is front-loaded.

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

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

With an output schema present and safety annotations in place, the description covers all operational essentials: admin access, filter semantics, limit bounds, and the relationship to marketing_graphics. No critical calling information is missing; the only minor gap is the lack of an explicit allowlist of content_type values, which is likely dynamic and out of scope for a static 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 description coverage is 0%, but the description fully compensates by explaining each parameter: since is an ISO timestamptz, ticker filters current items for a symbol, type is an allowlisted content_type or research_drop, and limit is constrained to 1–200 with a default of 50. This adds meaning far beyond the bare schema properties.

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 identifies the tool as returning the latest teasers and already-generated images, and explicitly contrasts it with marketing_graphics for live formats. It lacks a direct imperative verb like 'List' or 'Get', but the scope and resource are unmistakable.

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

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

Provides explicit routing guidance: use ticker for symbol-scoped items, type for cross-symbol content_type filtering, and since for the worker poll. It also tells the agent when to call marketing_graphics and when to reuse items[].images[], leaving no ambiguity about 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?

The description goes well beyond the annotations by disclosing blocking behavior ('Blocks until GCS has the PNG'), cache behavior ('or a cache hit'), the 'Do not poll' directive, the draft-format error condition, and the admin-only restriction. It also explains the force parameter's cache-bypass effect, giving the agent a clear model of the tool's runtime behavior.

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

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

The description is compact and front-loaded, with the most important facts ('Admin only', 'Render one live format', blocking behavior) in the first sentence. The Args section is clearly formatted and each line adds distinct value with no redundancy or filler.

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

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

Given the tool's moderate complexity, the description covers prerequisites (admin, live option), input format, blocking semantics, error behavior for drafts, and cache-related options. Since an output schema is present, return-value details are not required, and 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 description coverage is 0%, so the description carries the full burden for parameter meaning. It fully compensates by explaining content_id format ('gc:{id} or rd:{uuid}'), option_id origin ('live option from marketing_graphics'), and force semantics ('Bypass render cache'), covering all three parameters with actionable detail.

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

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

The description states a specific action: 'Render one live format and wait until image.url exists.' It clearly identifies the resource (live marketing format), the operation (render), and the async behavior, and it references the sibling tool 'marketing_graphics' as the source of valid option_ids, which helps distinguish this from related tools.

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

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

The description gives clear operational guidance: admin-only access, render live formats only, wait for the image URL rather than polling, and expect option_not_live for draft formats. It lacks an explicit 'when not to use this tool' or named alternative tools, but the draft-format exclusion and pointer to marketing_graphics provide strong contextual routing.

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 this is not read-only and not destructive, so the bar is lower. The description adds that moving to root is possible by omitting parent_id. However, it doesn't mention potential side effects like whether child items move along or if the operation is reversible.

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 main purpose, and uses a clear Args block. No unnecessary words or repetition.

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

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

For a simple move operation, the description covers the operation and parameters. It doesn't explain return values, but an output schema exists so that is not needed. It could mention whether the move is recursive or if there are prerequisites, but the essentials are present.

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 has no parameter descriptions (0% coverage), but the description's Args section fully explains both parameters: folder_id is the UUID to move, and parent_id is the new parent or null for root. This adds significant meaning beyond the schema.

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

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

The description clearly states the action (move), the resource (library folder), and the scope (under a different parent or root). It distinguishes itself from siblings like 'move_library_item' (moving items) and 'rename_library_folder' (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?

The description makes it clear this is for moving library folders, and the sibling names provide context (e.g., move_library_item for items). It doesn't explicitly exclude alternatives, but the scope is unambiguous.

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

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

Annotations already indicate the operation is not read-only and not destructive. The description adds the root-destination nuance but does not disclose other potential side effects (e.g., whether the item is removed from its previous folder), which are fairly obvious for a move operation. Given annotation coverage, the description provides adequate but not exceptional transparency.

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

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

The description is a single clear sentence plus a compact Args block that adds value (null behavior). No wasted words or redundancy beyond 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 two-parameter move operation with an output schema and annotations, the description provides all necessary context. It covers purpose, parameters, and destination semantics completely.

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

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

Schema description coverage is 0%, but the description's Args section fully explains both parameters, including the item_id as UUID and folder_id as destination with null-for-root behavior. This fully compensates for the missing schema descriptions.

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

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

The description uses a specific verb ('Move') and resource ('library document'), and clarifies destination options ('different folder' or 'root'). It clearly distinguishes from sibling tools like move_library_folder 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?

The description clearly implies when to use this tool—when moving an item between folders. It does not explicitly exclude alternatives, but the context is sufficient and unambiguous.

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

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

The description adds no behavioral context beyond the annotations. Annotations already declare readOnlyHint=false and destructiveHint=false, and the description simply repeats the rename action without mentioning side effects, permissions, reversibility, or effect on folder contents. It provides no additional transparency beyond what annotations convey.

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

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

The description is extremely concise, with the purpose stated first in a single sentence, followed by a minimal Args section that adds necessary parameter details. Every sentence earns its place, and there is no redundancy or 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?

Given the tool's simplicity (two required parameters, an output schema present, and a clear rename operation), the description covers the essential invocation details. It does not mention potential error conditions (e.g., folder not found, duplicate name), but these are not critical for a straightforward rename and are partly handled by the presence of an output schema.

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

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

With schema description coverage at 0%, the description compensates by defining both parameters: 'folder_id: The folder UUID' and 'name: New folder name'. This adds meaningful semantics beyond the bare schema (which only lists types and titles), clarifying that folder_id is the unique identifier and name is the replacement name.

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 'Rename a library folder' clearly specifies the action (rename) and the resource (library folder), distinguishing it from sibling tools like move_library_folder, create_library_folder, and delete_library_folder. It is a specific verb+resource statement, not a tautology.

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

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

No explicit when-to-use or alternative guidance is provided. The usage is implied by the tool's name and purpose—it is for renaming an existing library folder—but it does not state when it should be preferred over move or delete, nor any prerequisites like folder existence.

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

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

The description reveals key behaviors: it is a write operation (logging a bug), has a daily rate limit, and data goes to the same inbox as the terminal bug button. This adds context beyond the minimal annotations (readOnlyHint=false, destructiveHint=false) and discloses no contradictions.

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 concise and front-loaded with key purpose and usage. However, the parameter list uses a markdown 'Args:' block that is somewhat readable but could be more structured (e.g., bullet points) for easier parsing. Still, no unnecessary sentences.

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

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

Given 0% schema coverage and no enums, the description covers everything needed: parameter semantics, use case, rate limit, and admins' needs. The output schema exists, so return values need not be explained in the description. The tool is simple and the description is fully adequate.

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 fully compensates. Each parameter is explained with context: description's character range (10–2000), ticker as stock symbol, section as tab names, and page_url as optional terminal link. This adds substantial meaning beyond the schema titles.

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 'Log a bug' with a specific verb and resource. It also mentions the rate limit (5 per user per day) and distinguishes itself from sibling tools, none of which relate to bug reporting.

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?

Explicit guidance is provided: use only when the user asks or when a real data/UI error is confirmed, and do not file speculative bugs. It also advises passing ticker/section for admin convenience, giving clear when-to-use and what-to-avoid instructions.

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?

Adds substantial behavioral detail beyond annotations: the call is async (returns when queued, do not poll), it consumes a monthly grant, and prepaid credits are rejected. Annotations (readOnlyHint=false, destructiveHint=false) are consistent with a side-effecting but non-destructive queueing tool — no contradiction.

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

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

Well front-loaded: purpose, then billing/quotas, then async behavior, then args. All sentences earn their place, especially the concrete force example. Slightly long at ~100 words, but the quota breakdown and re-run nuance justify the length for a tool with billing implications.

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

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

Covers everything needed to invoke correctly: quotas, billing exclusions, async return behavior, force semantics, and parameter enrichment. The output schema covers return values. Minor gap: no mention of where completed results are delivered, though the 'do not poll' note mitigates the uncertainty.

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

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

With 0% schema description coverage, the description fully compensates: ticker gets format and example ('AAPL'), and force gets precise semantics ('Re-queue every chapter even when a current report exists') plus a concrete when-to-use example (ZS thesis written as soybeans). This far exceeds the bare schema titles.

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

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

Opens with a specific verb-resource-scope: 'Queue a full DeepDive suite for a stock using a monthly custom-run grant.' This adds queueing behavior and the grant mechanism beyond the title, and no sibling tool queues analysis runs, so it is clearly differentiated.

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 explicit when-to/not-to-use context: prepaid search credits are excluded, plan quotas are spelled out (Free 0, Basic 10, Pro 50), and re-running an already-unlocked ticker consumes no grant. It does not name an alternative sibling, but no sibling closely overlaps this action.

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 the safety profile is covered. The description adds helpful context about scoping to the authenticated user's library and the max result cap of 50, but it does not detail ranking, pagination, or result shape beyond what the output schema provides.

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 concise, with a clear front-loaded purpose sentence followed by a compact Args block. Every sentence adds information, and there is no redundancy with the schema beyond necessary clarification.

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 does not need to explain return values. It adequately covers the tool's purpose, user scope, and parameter behavior, and annotations cover safety. A minor gap is lack of mention of result sorting or that it searches document content vs metadata, but overall it is complete for a simple search 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 description coverage is 0%, so the description must compensate. It defines query as 'Search terms' and limit as 'Max results (default 20, capped at 50),' adding the cap information that is not present in the schema. This is sufficient for both parameters, though 'Search terms' is somewhat generic.

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 action: 'Full-text search across the authenticated user's library documents.' It identifies the resource (library documents) and scope (authenticated user's), and distinguishes itself from sibling finance_search by specifying 'library documents' rather than financial data.

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

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

The description implies usage for full-text searching within the user's library, but it does not explicitly state when to use this tool over alternatives like list_library_items or finance_search, nor does it mention exclusions. The context is clear but lacks direct guidance.

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

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

Annotations only indicate non-readonly and non-destructive. The description adds critical behavioral detail: the draft is accepted immediately, the readable entry is generated at end of day, and the draft id cannot be used with list_journal/get_journal_entry until then. This is beyond what annotations convey.

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

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

The description is compact and front-loaded with the primary action, followed by essential caveats. The Args section is clearly structured. Every sentence adds value without redundancy.

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

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

For a tool with two-phase behavior and an id mismatch, the description covers all key points: same-day resubmissions, immediate acceptance, automatic generation, appearance in list_journal, and the temporary id discrepancy. It is complete despite the lack of parameter details 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 coverage is 0%, but the description provides an Args section explaining entry_date as 'Day the draft is for (YYYY-MM-DD)' and content as 'Draft text.' This compensates for the schema's bare property names and gives format guidance.

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 'Submit a journal draft for a day,' a specific verb+resource+scope statement. It further distinguishes itself from siblings like list_journal and get_journal_entry by clarifying that the returned draft id is not the same as the entry id until the end of day.

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

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

The description provides clear context for use: same-day resubmissions are retained as separate drafts, and the entry appears in list_journal only after end-of-day processing. It doesn't explicitly name alternatives or when-not-to-use, but the context is sufficient for an agent to select this tool for draft submission.

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

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

Annotations already provide readOnlyHint=false (mutation) and destructiveHint=false (not destructive). The description adds key behavior: content edits create a new version, document type does NOT change, and content format handling (markdown vs HTML). This goes beyond annotations and is critical for agent expectation. No contradiction, though it could mention if title edits also create versions (unclear), but that's a minor gap.

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

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

The description is concise: two sentences then an Args list. It front-loads the purpose and version behavior. The Args list is clean and matches schema parameters. Every sentence adds value—the format guidance for content is essential. No fluff or repetition.

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

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

The tool has an output schema (not detailed in the prompt, but present), so return values need not be explained. With 3 params, the description covers the behavior of each. It doesn't mention error cases (e.g., invalid item_id) but that's not typically required. The versioning behavior is explained well. Missing: whether title-only updates create versions, but that's minor. Overall, sufficient for an agent to call correctly.

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

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

Schema description coverage is 0%, so description must compensate. The description explains that 'title' and 'content' are optional and lists their semantics (title vs content). It clarifies that content is markdown or HTML. However, it doesn't explain 'item_id' beyond being a UUID, but the schema name 'Item Id' and required status are self-explanatory. Baseline for low coverage is 1, but description adds meaningful detail, hence 3.

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

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

The description states a specific verb ('Update') and resource ('library document'), and clarifies scope: title and/or content, with content edits creating a new version. It differentiates from siblings like 'create_library_item' and 'delete_library_item' by implying this is for existing items, and from 'list_library_item_versions' by noting version creation. The 'versioned' in title is reinforced by the description.

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

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

The description clearly indicates when to use it: to modify an existing library item's title/content, and implies not for creating or deleting (siblings exist). It mentions content handling for markdown vs HTML, which is a context-specific instruction. However, it doesn't explicitly state when NOT to use it or name alternative siblings for creation/deletion, but the context signals include those siblings and the purpose 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?

The description states it updates a watchlist but does not disclose whether the symbol list is replaced entirely or merged, or what happens if name or symbols are null. Annotations indicate it's a write (readOnlyHint=false) but not destructive (destructiveHint=false), yet the description adds no further behavioral context.

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

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

The description is concise with a one-sentence summary followed by an Args list. It is front-loaded and free of fluff, but the Args block partially duplicates schema information and could be streamlined.

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 update tool, the description should clarify that symbols replaces the entire list and note any permissions or existence requirements. The output schema may cover return values, but key behavioral details are missing, making the description incomplete for a mutation operation.

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

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

The description adds brief semantic labels: 'The watchlist UUID' for watchlist_id, 'New name (optional)' for name, and 'Updated list of symbols (optional)' for symbols. This goes beyond the raw schema but lacks detail on symbol format, replacement behavior, or validation rules.

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

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

The description clearly states the tool updates a watchlist's name and/or symbols, identifying the specific action and resource. This distinguishes it from sibling tools like create_watchlist and list_watchlists, though it does not explicitly name an alternative.

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, such as creating a new watchlist or deleting one. The description does not mention any prerequisites or conditions for updating, leaving the decision context unspecified.

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