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

With no annotations provided, the description carries the full burden of behavioral disclosure. It adds a crucial caveat that cancelling a working order does not close a filled position, which is non-obvious and valuable. It does not cover all edge cases (e.g., idempotency, errors), but the disclosed behavior is significant.

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: a one-line purpose, a critical caveat, and a simple Args section. Every sentence adds value with 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?

For a simple tool with one parameter and an output schema, the description covers the essential aspects: purpose, behavioral caveat, and parameter meaning. The caveat about filled positions is an important contextual edge case. The output schema handles return values, so no further description is necessary.

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

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

The input schema only defines 'broker_order_id' as a string. The description adds essential semantics by stating it is 'Order id returned by `place_order`,' clarifying the parameter's origin and role, which fully 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's purpose with a specific verb and resource: 'Cancel a working order.' It also distinguishes itself from the sibling 'close_broker_position' by explicitly noting that this tool does not close filled positions.

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

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

The description provides clear context for when to use the tool: when the order is still 'working.' It explicitly states when not to use it ('if the entry already filled') and implies an alternative (closing the position explicitly), though it does not name a specific alternative tool.

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

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

With no annotations, the description fully carries the behavioral burden. It discloses that the close executes at market and that it does not close the thesis, adding valuable context about side effects and next steps. It does not mention error cases, but for a simple one-parameter operation this is sufficient.

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

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

The description is compact and front-loaded, with the core action in the first sentence and a critical workflow note immediately after. The Args section is simple and redundant with the schema, but does not add unnecessary length.

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

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

Given the tool has only one parameter and an output schema exists, the description covers the essential workflow and key caveat (broker close vs thesis close). It does not describe behavior for invalid symbols or partial closes, but these are not critical for a straightforward market close 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 basic meaning to the `symbol` parameter by calling it a 'Stock symbol of the position to close', which clarifies the role of the parameter beyond the schema title. However, it largely restates the parameter name and does not provide format or validation details, so it only partially 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 states specifically 'Close an open position at market' with a clear verb and resource. It distinguishes from the sibling tool `close_thesis` by explicitly noting that closing at the broker does not close the thesis, making the tool's role 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?

It provides explicit sequential guidance: follow this tool with `close_thesis` and the fill price to record realised R. This clearly indicates when and how to use the tool in context, though it doesn't enumerate exclusions or alternative tools beyond the implied workflow.

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

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

With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'Realised R is computed from the recorded entry and stop, so the result is comparable across positions of different sizes.' It also clarifies the outcome parameter with allowed values and explains the note field's purpose. It does not mention side effects or error conditions, but it provides meaningful insight into how the tool behaves beyond the mere action of closing.

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 starts with a one-sentence purpose, adds a brief note about Realised R for context, then lists parameters in a clear arg format. There is no verbose filler. Every sentence earns its place, and the structure is easy to scan.

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

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

The tool has moderate complexity with four parameters and an output schema. The description explains the core purpose, parameter meanings, and a calculation detail. It does not explain the return value, but an output schema exists, so that's acceptable. It could be improved by clarifying side effects or differences from close_broker_position, but overall it is sufficiently complete for an agent to invoke correctly.

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

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

The schema description coverage is 0%, so the description fully compensates by documenting all four parameters: thesis_id (identifier from journal_thesis), outcome (with enumerated strings), exit_price (fill price, where there was one), and note (actual events, especially for wrong-reason cases). This adds significant meaning beyond the bare schema, making parameter usage clear.

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

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

The description clearly states the tool's function: 'Close a thesis, recording how it actually resolved.' This uses a specific verb ('close') and resource ('thesis'), and adds the purpose of recording resolution. The name alone is unambiguous, and the description distinguishes it from sibling tools like close_broker_position by focusing on the thesis lifecycle.

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: you use this tool when you need to close a thesis and record its outcome. It does not explicitly mention alternatives or exclusions, such as when to use close_broker_position instead. However, the purpose is clear enough that an agent can infer the appropriate context, but explicit guidance on when not to use it is missing.

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

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

With no annotations, the description carries the burden. It discloses a notable behavioral trait: refusing to return data for accounts it cannot prove are paper accounts. It does not mention safety, permissions, or rate limits, but for a simple read-only tool 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?

Three concise sentences, front-loaded with the main purpose, followed by a behavioral warning and practical usage advice. No wasted words.

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

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

Given the zero-parameter input and existing output schema, the description covers the essential purpose, the paper-account restriction, and how to use the result. It could mention what happens when it refuses, but overall it is complete for this simple 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?

There are zero parameters and the input schema is empty. The description mentions the output fields rather than parameters, but with no schema coverage burden, the baseline of 4 applies.

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

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

The description clearly identifies the tool as providing paper account state including equity, cash, buying power, and positions value. It distinguishes from siblings like get_broker_positions by specifying 'paper account,' though it lacks an explicit verb.

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

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

It provides context that this is for paper accounts and recommends using the returned equity as input to size_position. However, it does not explicitly state when to prefer this over alternatives or when not to use it.

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

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

No annotations are provided, so the description must disclose behavioral traits. It states the ordering (newest first) but does not explicitly confirm this is a read-only operation, mention any side effects, or describe pagination behavior. For a getter, the absence of explicit read-only disclosure or note about absence of side effects is a notable gap.

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

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

The description is extremely concise and front-loaded. The first line states the core purpose and ordering, followed by a compact parameter list. Every sentence earns its place 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 simple two-parameter retrieval tool with an output schema, the description covers essential usage aspects: what is returned (orders), ordering, and parameter meanings. It lacks explicit return-structure details, but the output schema compensates. No critical gaps remain.

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

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

The description fully explains both parameters, going beyond the schema: status lists accepted values ('open', 'closed' or 'all') and limit defines a maximum count. This is essential given 0% schema description coverage.

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

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

The description clearly identifies the resource (orders at the paper broker) and provides an ordering (newest first), which distinguishes it from sibling tools like get_broker_positions. However, it lacks an explicit verb like 'retrieves' or 'lists', relying on the tool name to convey the action.

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

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

Usage context is implied by the tool name and description (retrieving broker orders), but no explicit guidance is given about when to use this tool versus alternatives such as get_broker_positions or place_order. No exclusions or prerequisites are stated.

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

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

No annotations are provided, so the description carries the full burden. It adds useful context: the operation is at the 'paper broker' and includes unrealised P&L, indicating a read-only snapshot. However, it does not disclose potential return format, ordering, pagination, or data freshness, which would be valuable for a read operation.

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 sentence, front-loaded with 'Open positions', and contains no filler or redundant terms. It is concise and structurally ideal.

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

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

For a zero-parameter tool with an output schema, the description sufficiently explains what is returned. It includes useful context about the paper broker and unrealised P&L. However, it does not mention potential limitations like the current date range or position status, which could be relevant in some contexts.

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

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

The input schema has zero parameters, so the baseline is 4. The description correctly implies no arguments are needed and adds no conflicting information. No additional parameter semantics are required.

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 'Open positions at the paper broker, with unrealised P&L' uses a specific verb ('get') and resource ('broker positions'), and adds scope ('paper broker') and content details ('unrealised P&L'). This clearly distinguishes it from sibling tools like get_broker_orders.

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

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

No explicit when-to-use or alternative guidance is provided. The description implies retrieval of open positions, which is a clear context, but it does not name alternatives such as get_broker_orders or close_broker_position. This is adequate but could be improved with explicit exclusions.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It only mentions ordering ('newest first') but omits other behaviors like pagination, error handling, or rate limits. The read-only nature is implied but not explicitly stated.

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

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

The description is concise and well-structured, with a one-line summary followed by a labeled Args section. Each parameter explanation is brief and useful, with no superfluous 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 description covers the essentials for a simple list tool, but lacks usage context and any mention of alternatives. Since no annotations are present, the description could do more to clarify behavior, though the existence of an output schema reduces the need to explain return values.

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 provides clear meanings for all three parameters: ticker is a stock symbol, forms is an optional filter with an example, and limit is the maximum count. This fully compensates for the 0% schema coverage.

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

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

The description clearly states it returns recent SEC filings for a company, ordered newest first. It is specific about the resource and action, but does not explicitly differentiate from sibling tools like get_filing_text or search_filing_text.

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 provided on when to use this tool versus alternatives. There is no mention of use cases, prerequisites, or exclusions, leaving the agent to infer when this is the appropriate choice.

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

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

With no annotations provided, the description carries the full burden and excels. It discloses key behaviors: markup stripping, pagination via windows, truncation signaling through `truncated` and `next_offset`, and the hierarchy of `accession` over `form`. Also notes the `max_chars` cap of 100,000, preventing silent data loss.

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

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

The description is well-structured, starting with a one-sentence summary, followed by usage context, important pagination behavior, and an Args list. Every sentence adds value—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?

Despite having an output schema (not shown), the description still provides essential context: purpose, usage scenarios, pagination mechanics, and parameter semantics. It covers all aspects an agent needs to correctly select and invoke the tool, making it complete for practical use.

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

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

Schema coverage is 0%, but the description fully compensates. Each parameter is explained with its role, including special behaviors: `accession` takes precedence, `form` selects newest filing of that form, `offset` for paging, and `max_chars` with an explicit cap. 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 first sentence clearly states what the tool does: retrieves filing text as filed, with markup stripped, in windows. It distinguishes itself from siblings by noting that `get_filings` provides dates while this tool provides the actual text, and `search_filing_text` is for targeted searches.

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

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

Explicitly states when to use the tool: 'Use this when the numbers raise a question they cannot answer' with concrete examples. It also gives an alternative: 'Prefer `search_filing_text` when you know what you are looking for.' This provides clear decision rules for tool selection.

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

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

No annotations are provided, so the description carries the full burden. It adds meaningful behavioral context: ordering ('oldest to newest'), per-point fiscal year and source filing, and visibility of restated figures. This goes well beyond what the schema provides, though it omits failure or availability details.

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

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

The description is front-loaded with a one-sentence summary, followed by a brief use-case sentence and a structured Args list. No filler 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?

Given the simple data-retrieval nature and presence of an output schema, the description covers purpose, usage, parameters, and key behavioral details. It is complete for an agent to invoke correctly.

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

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

Schema description coverage is 0%, but the description's Args section documents every parameter with examples ('NVDA', 'revenue', 'net_income', 'annual' vs 'quarterly', maximum periods). This fully compensates for the schema gap.

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

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

The description opens with a specific verb+resource: 'Historical series for one line item, oldest to newest.' It clearly distinguishes from sibling tools by emphasizing 'one line item' and the chronological ordering, which sets it apart from broader financials or metrics tools.

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

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

It explicitly states 'Use this for growth rates and trends,' conveying when the tool is appropriate. However, it does not name alternative tools or exclusions, so it lacks explicit when-not-to-use 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?

No annotations are provided, so the description must carry the burden of behavioral disclosure. It does reveal that missing line items appear under 'unavailable' and states the data source and return fields (concept, period, filing). However, it omits potential behaviors like authentication requirements, rate limits, 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 concise and well-structured with a clear summary paragraph followed by an Args list. Every sentence serves a purpose—covering what it does, what it returns, how missing items behave, and parameter definitions—without unnecessary verbosity.

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 tool, the description covers the primary return structure (concept, period, filing) and the 'unavailable' behavior for missing items. Combined with an output schema, this is sufficiently complete, though it doesn't address edge cases like invalid tickers or empty financial statements.

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

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

The Args section explicitly defines ticker with an example and period with allowed values ('annual' or 'quarterly'), compensating for the schema's 0% description coverage. This adds practical meaning 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 states it retrieves the latest full financial statement from SEC XBRL filings, listing all line items. It distinguishes from siblings by emphasizing 'full' and 'every available line item,' though it does not explicitly name alternative 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?

No guidance is given on when to use this tool versus alternatives such as get_financial_history or get_metrics. The description only explains what it does, leaving usage decisions to the agent without any exclusions or alternative recommendations.

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

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

No annotations are provided, so the description carries the burden. It explains that 'limit' controls the maximum number of filings returned, which adds some behavioral context. However, it does not disclose any side effects, privileges, or additional behavior, though as a read-only operation this is less critical. The description offers minimal but adequate 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 concise with a two-sentence purpose followed by a compact arg list. It front-loads the main purpose and avoids any wasted words, making it easy for an agent to parse quickly.

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

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

There is an output schema present, so return values are covered externally. The description gives the essential purpose and parameter details, but it does not clarify what 'Recent' means (e.g., time window) or any sorting/ordering. For a simple retrieval tool, this is nearly complete, with only a minor gap about the recency definition.

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

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

Despite 0% schema description coverage, the description clearly explains both parameters: 'ticker: Stock symbol' and 'limit: Maximum Form 4 filings to return.' This adds meaningful semantics beyond the bare schema types and defaults, fully compensating for the lack of 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 clearly states a specific resource: 'Recent Form 4 insider transaction filings for a company.' It uses a specific verb 'get' and distinguishes itself from sibling tools like get_filings and get_filing_text by focusing on insider activity.

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 insider transaction data based on the Form 4 specificity, but it does not explicitly mention when to use this tool versus alternatives, nor does it provide exclusions or alternative tool names. This is implied rather than stated.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It discloses that the response includes 1-, 3-, and 12-month changes, but it does not mention error handling, data source, or explicitly confirm read-only behavior (though the name 'get' implies it). This is minimal but not misleading.

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 plus a compact args block. It is front-loaded with the main purpose and includes only essential information without redundancy. Every sentence earns its place.

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

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

For a one-parameter getter with an output schema, the description covers the essentials: what it does, parameter meaning, and how to discover keys. The phrase 'in detail' is slightly vague, but the output schema likely specifies the return structure. It is complete enough for a simple retrieval tool.

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

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

The schema only specifies 'key' as a string, but the description gives concrete examples ('treasury_10y', 'core_cpi', 'vix') and directs users to get_macro_snapshot to see all valid keys. This fully compensates for the 0% schema description coverage and makes the parameter semantics clear.

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

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

The description clearly states the tool retrieves one macro series in detail, including 1-, 3-, and 12-month changes. This verb+resource structure distinguishes it from siblings like get_macro_snapshot, and the example keys (e.g., 'treasury_10y') add clarity.

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

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

The description implies when to use this tool (for a specific series) versus get_macro_snapshot (to see all series). It provides example keys and advises calling the sibling to discover available keys, but does not explicitly state exclusions or alternative conditions beyond that.

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

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

With no annotations, the description carries full responsibility. It discloses the data content (FRED series id, observation date, 1/3/12-month changes), the computation basis (last real print vs calendar date), and failure handling (unavailable list). This is exemplary behavioral 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 front-loaded with the core purpose, then provides essential details in a compact, structured way. Every sentence adds value: data content, computation nuance, failure handling, and parameter guidance. No redundant text.

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, so return values need not be explained. The description covers data provenance, change calculations, error resilience, and parameter usage. It is complete for the tool's complexity, with no obvious gaps.

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

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

Schema coverage is 0%, so the description must compensate. It explains the `series` parameter with an example (["treasury_10y", "curve_10y_2y"]) and states that omitting it returns all series. This adds meaningful semantics beyond the bare schema.

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

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

The description clearly states it returns current macro conditions from FRED, listing specific categories (rates, curve, inflation, jobs, vol). This is a specific verb+resource (get + macro snapshot) and distinguishes itself from siblings like get_macro_series by being a composite snapshot with computed changes.

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

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

It explicitly instructs to always read rates and inflation here, warning that memory is wrong by whole percentage points. This provides a strong when-to-use directive and a when-not-to-use (memory). It also explains the optional `series` parameter for subsetting, giving clear usage context.

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

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

No annotations are provided, so the description carries the burden. It discloses the cap of 50 and that 'top' returns 'each' (gainers and losers), and adds a caveat about the data's nature. But it does not describe pagination, sorting, or what happens with no arguments, though an output schema exists.

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

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

The description is short and well-structured: a one-line purpose, a relevant caveat, and a clear args section. Every sentence earns its place, and it is front-loaded with the main 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?

For a simple tool with one parameter and an output schema, the description covers purpose, parameter semantics, and a key behavioral caveat. It lacks explicit alternative references but is otherwise complete for the tool's complexity.

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

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

Schema description coverage is 0%, but the description compensates by explaining 'top' as 'How many of each to return, capped at 50,' adding meaning beyond the raw schema fields. This is sufficient for the single parameter.

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

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

The description clearly states the tool returns today's largest percentage gainers and losers, which is a specific verb+resource+scope. It distinguishes from siblings like get_most_active by focusing on percentage moves rather than volume or activity.

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 offers context with 'A starting list, not a signal' and notes that large single-day moves are already priced, implicitly warning against overuse. However, it does not name alternative tools or explicitly state when to use this versus another tool.

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

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

With no annotations, the description carries full disclosure burden. It reveals methodology ('Computed from SEC filings rather than estimated'), notes a caveat ('on average balances where available'), and discloses output transparency ('Each metric lists the line items it was computed from and the period it covers'). It does not mention rate limits, error behavior, or update frequency, but these are less critical for a read-only metrics tool.

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

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

The description is well-organized: a one-line summary, a methodology paragraph, a line about output structure, an explicit usage preference, and a concise Args list. Every sentence provides distinct value, with no fluff or repetition. Front-loading with the core purpose makes it easy to scan.

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

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

The tool has moderate complexity (2 params, no nested objects) and an output schema, so the description need not detail return values. It covers data source, metric list, methodology caveats, output transparency, and sibling differentiation. This is complete for an agent to select and invoke the tool correctly.

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

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

The schema has 0% description coverage, but the description's Args section compensates fully. It explains 'ticker' as a stock symbol with an example, and clarifies 'history_years' as 'Periods to span when computing growth rates,' which adds meaning beyond the schema's name and default. This is high-value 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+resource: 'Derived financial metrics for a company' and enumerates exact metric categories (margins, returns, growth, leverage). It clearly distinguishes from siblings by stating 'Prefer this over deriving ratios yourself from get_financials,' naming the alternative tool.

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

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

The description explicitly tells the agent when to use this tool: whenever derived ratios are needed, and when not to use it (don't derive ratios yourself from get_financials). It also states the data source (SEC filings rather than estimated), giving context for trustworthiness. This is clear usage guidance with a named alternative.

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

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

No annotations are provided, so the description carries the burden of behavioral disclosure. It adds useful constraints (top capped at 50 and by options), but does not explicitly state that this is a read-only operation or describe any 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 extremely concise and front-loaded, with a one-sentence purpose and two bullet-point argument explanations. No unnecessary 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?

For a simple getter with two parameters and an output schema, the description covers the core purpose and parameter semantics. It lacks usage guidance, but that is addressed in a separate dimension; overall it is adequate for its complexity.

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?

Both parameters are meaningfully explained beyond the schema: 'by' is defined as 'volume' or 'trades', and 'top' is described as how many to return with a cap of 50. This fully compensates for the schema's lack of descriptions.

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

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

The description clearly states the tool returns the day's most heavily traded names, which is a specific resource and action. However, it does not distinguish this from sibling tools such as get_market_movers, so it lacks sibling differentiation.

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

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

No guidance is provided on when to use this tool versus alternatives. The description only defines the output and parameters, with no mention of use cases, exclusions, or alternative 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?

No annotations exist, so the description carries the burden of disclosure. It explains the content and gives a usage directive, but it does not mention whether this is a read-only operation, any rate limits, or how the data should be interpreted. This is adequate but sparse.

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 two concise sentences, front-loaded with the primary purpose and followed by a practical usage note. Every word earns its place, with no redundancy.

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

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

For a parameterless tool with an output schema, the description is complete enough: it states what is returned and how to use it. It could optionally note that it is a safe read-only call, but this is not essential given the output schema and lack of parameters.

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

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

The tool has zero parameters, and the schema is empty, so the description needs to add no parameter-level meaning. The baseline of 4 applies here because there is nothing to describe beyond what the schema already shows.

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 what the tool does: it retrieves the desk's standing risk limits along with the reasoning behind each. This specific verb+resource framing distinguishes it from sibling tools like get_financials or place_order, which address different domains.

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

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

It provides explicit usage context: quote these limits verbatim when explaining a veto. While it does not name alternative tools, the veto-explanation scenario gives a concrete 'when to use' signal, which is more than many tool descriptions offer.

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

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

With no annotations, the description carries the full burden. It transparently explains data source (SIP tape), the fact that volume is full-market, and the null-handling behavior under `limitations`. It lacks explicit read-only confirmation or rate-limit information, but the read-only nature is strongly implied by the tool name and 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 well-structured and front-loaded with the purpose. Each paragraph earns its place, covering data source, return contents, null behavior, and parameters. The Args list is concise yet informative, with no repetition of schema defaults.

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

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

Given the tool's complexity and the presence of an output schema, the description is thorough. It covers data source, parameter semantics, null handling, and expected return components, making it fully sufficient for an agent to invoke correctly.

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

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

The schema has 0% coverage, but the description's Args section provides meaningful explanations for all three parameters, including the role of benchmark and how lookback_days relates to the 200-day moving average. This goes well beyond 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?

The description clearly states the tool's purpose as providing a 'technical picture for a symbol' and enumerates specific components (trend, momentum, volatility, key levels). It differentiates from sibling tools like get_financials and get_metrics by focusing on technical analysis from daily bars, with details such as moving-average structure, RSI, and ATR.

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 obtaining daily-bar technicals, emphasizing the consolidated SIP tape and full-market volume, which is useful context. However, it does not explicitly state when to prefer this tool over alternatives or provide exclusions, so it falls short of a 5.

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

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

No annotations are provided, so the description carries the full burden. It adds that the result includes evidence and falsifiers, but doesn't state whether this is a read-only operation, error behavior, or any prerequisites. The verb 'get' implies retrieval, but that is minimal.

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

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

Two sentences, directly states purpose and parameter origin, with no filler. Every word 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?

The tool is simple (one required param) and an output schema exists, so the description adequately describes the return envelope. It covers the key contextual link to journal_thesis, though it could mention when to use it relative to list_theses.

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 compensates by defining thesis_id as 'Identifier returned by journal_thesis,' providing provenance. This adds meaning beyond the bare string schema, though it doesn't detail format or validation.

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 'get' and names the resource ('recorded thesis') with its scope ('in full, including its evidence and falsifiers'). It distinguishes from sibling list_theses/journal_theses by indicating a single full thesis, though it does not explicitly name alternatives.

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

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

It provides context: use with a thesis_id returned by journal_thesis, which implies a workflow. However, it lacks explicit exclusions or comparison to list_theses or close_thesis, so the guidance is only implied rather than clearly stated.

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

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

With no annotations, the description carries the full burden. It discloses the persistence behavior ('stored thesis'), the requirement that falsifiers be provided, and the ethical rationale for immediate recording. It could further clarify whether this overwrites existing entries or is append-only, but for a journaling tool the described side effect is sufficiently clear.

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 divided into an opening purpose/ethics paragraph and a labeled Args list. There is no fluff; every line adds semantic value. For a tool with 15 parameters, the length is justified and the format makes it 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?

The tool has 15 parameters with conditional requirements and an output schema. The description covers all parameters, provides usage timing, explains return value, and integrates references to sibling tools like size_position. It is complete enough for an agent to invoke and understand the result without additional context.

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

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

Schema coverage is 0%, so the description fully compensates. Every parameter is explained: falsifiers are defined with examples, evidence suggests a structure, entry/stop are marked conditionally required, and direction/horizon/conviction list their allowed values. This surpasses the schema's bare structure.

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 'Record a call so it can be scored later, and return the stored thesis.' This clearly states the verb (record), resource (call/thesis), and purpose (scoring later). It also distinguishes itself from sibling tools like list_theses and get_thesis by focusing on the write operation.

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

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

The description provides strong timing guidance: 'Write this at the moment the call is made' and explains why that matters. It also clarifies when to use direction='watch'. However, it does not explicitly state when NOT to use the tool or name alternative tools for retrieval, so it falls short of a 5.

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

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

No annotations exist, so the description carries the full burden of behavioral disclosure. It only mentions a capability ('can resolve') without describing what the tool actually does, whether it's read-only, what it returns, or any side effects. This is essentially no behavioral disclosure.

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

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

The description is extremely short but under-specified. It's a vague fragment rather than a concise, informative statement. It doesn't earn its place because it fails to communicate the tool's function effectively.

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

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

Despite having no parameters and an output schema, the description is incomplete because it doesn't clearly state what the line items are, how they are sourced, or how to interpret the result. A simple list tool still needs a clear purpose statement.

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

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

The tool has zero parameters, so the schema provides full coverage. Per the rubric, 0 params warrants a baseline of 4; the description doesn't need to add parameter 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 is a noun phrase, not a clear verb+resource. It essentially restates the tool name with the qualifier 'this server can resolve,' which doesn't clearly state the action of listing or returning line items. It doesn't distinguish from sibling tools like get_financials.

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 provided on when to use this tool versus alternatives. There is no context, prerequisites, or examples. The intended usage is only implied by the name and vague description, but no explicit direction is given.

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

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

With no annotations, the description carries the full burden. It does disclose the ordering behavior ('newest first') and optional filtering (ticker, status, limit), which is useful. However, it does not explicitly state that the operation is read-only or describe any side effects, error conditions, or scope limitations beyond the listed arguments.

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, using a short opening phrase and a clean 'Args:' block to document parameters. There is no wasted wording or redundant information.

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

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

For a simple list tool with three optional parameters and an output schema, the description covers the core purpose, ordering, and parameters. However, it omits any usage guidance or contextual examples, making it slightly incomplete for an agent that needs to decide when to invoke this tool over others.

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

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

The schema has 0% description coverage, so the description must compensate. It provides clear meanings for all three parameters: ticker as an optional symbol filter, status as an optional 'open' or 'closed' filter, and limit as the maximum number to return. This adds significant value 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 states 'Recorded theses, newest first,' identifying the resource and ordering. The tool name 'list_theses' clarifies the action, and it is distinguishable from siblings like get_thesis or close_thesis. However, the description lacks an explicit verb like 'List' or 'Retrieve,' making it slightly less direct.

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 get_thesis or close_thesis. The description only lists parameters and does not mention use cases, exclusions, or preferred scenarios.

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

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

With no annotations provided, the description carries full responsibility for behavioral disclosure. It clearly states that orders are sent to a paper broker, that they go out as brackets, and that submission does not mean fill. It also enumerates refusal conditions, providing transparency about failure modes.

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

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

The description is efficiently structured: a one-line purpose, then key constraints, refusal conditions, a note on bracket behavior, and a pointer to a related tool. No sentence is wasted; the length is justified by the richness of safety-critical information.

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

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

Given the tool's complexity as a side-effecting order placement, the description covers the preconditions (risk approval), the exact input, the operational behavior (brackets), and the post-submission expectation (check get_broker_orders). The presence of an output schema means return-value details are handled separately, so the description is appropriately complete.

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

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

The schema provides only the parameter name and type with no description. The tool description compensates by explaining that thesis_id is 'the identifier returned by journal_thesis.' This gives the agent exactly the semantic information needed to invoke the tool correctly.

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

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

The description opens with a specific verb+resource: 'Send a journalled, risk-approved thesis to the paper broker.' This clearly distinguishes the tool from siblings like journal_thesis (creates the thesis) and size_position (sizes it). It states exactly what the tool does and its 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?

The description explicitly explains when to use the tool (for placing orders from approved theses) and lists refusal conditions that act as when-not-to-use guidance. It also points to get_broker_orders for checking fills, effectively directing users away from using this tool for that 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?

With no annotations provided, the description carries the full burden. It discloses concrete behavioral details: symbols with missing history appear under 'unavailable' rather than being silently dropped, each symbol costs a separate history request (rate/cost implication), and the tool returns specific metrics (trend, RSI, ATR, drawdown). This goes well beyond a generic read-only expectation, though it does not mention edge cases like invalid symbols or network errors.

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

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

The description is well-structured: a one-sentence summary, a supporting paragraph on usage and outputs, a clear non-goal statement, and a compact Args section. Every sentence adds information; there is no fluff or repetition. The front-loading makes the core purpose immediately obvious.

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

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

Despite having an output schema, the description enriches context by explaining the 'unavailable' behavior, the nature of the metrics, and the per-symbol cost. The tool has only three parameters and no nested objects, so the description covers the full decision-making surface. It is complete for both 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 coverage is 0%, so the description must explain all parameters, and it does so thoroughly. 'symbols' is described with a limit and per-symbol cost, 'benchmark' is explained as the relative-strength reference with default SPY, and 'lookback_days' is defined as calendar days of history. This adds meaning the raw schema lacks.

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

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

The description opens with a specific verb phrase 'Order a candidate list by relative strength', immediately distinguishing this as a ranking/screening tool compared to sibling data-retrieval tools. It further clarifies the output purpose ('shortlist worth spending the research agents on') and explicitly states what it does not do ('does not judge 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 phrase 'Turns a raw list into a shortlist worth spending the research agents on' provides clear context for when to use this tool (as a pre-research screening step). It also gives an explicit non-use ('does not judge them') to set expectations. However, it does not name alternative tools, so it stops short of a full 5.

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

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

With no annotations, the description carries the burden. It clearly states the tool 'reports' mismatches and enumerates the two kinds reported. The verb 'Compare' and 'reports' imply a read-only operation, though it doesn't explicitly confirm no side effects. The added context about portfolio heat is useful 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 three sentences, front-loaded with the main purpose. The subsequent sentences add valuable rationale and detail about mismatch types without waste. Every sentence contributes.

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

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

For a zero-parameter tool with an output schema, the description fully explains what it does, why it matters, and what it reports. It is complete for an agent to select and invoke correctly.

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

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

The tool has zero parameters, and the schema confirms complete coverage. The description therefore doesn't need to explain parameter usage; it adds meaning by describing what is compared and reported, which is sufficient.

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 resources: 'Compare broker positions against open journalled theses.' This clearly distinguishes it from siblings like get_broker_positions or list_theses, as it focuses on reconciliation between the two.

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

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

It explains why this tool is needed — portfolio heat comes from the journal, so positions without theses are invisible to risk checks. This implies when to use it (to find untracked positions or unfilled theses), but it doesn't explicitly state exclusions or name alternative tools.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that results are verbatim passages, highlights that this is cheaper than paging a full filing, and explains the meaning of a no-match result. It also documents behavioral nuances like accession precedence, which is valuable context beyond the schema.

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

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

The description is purpose-first and concise, with the core function stated in the first sentence. The cost comparison sentence adds practical value, and the Args section is a compact, scannable list. It is slightly longer than strictly necessary but every sentence contributes to understanding.

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

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

This description is highly complete for a search tool with 6 parameters and an output schema. It explains all parameters, provides usage guidance, defines no-match semantics, and clarifies precedence. The presence of an output schema means the return structure need not be described. Minor omissions like error handling are not critical for tool 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?

The description provides a meaningful definition for each of the 6 parameters, including real-world examples (query: 'stock-based compensation'), precedence semantics (accession takes precedence), and the unit for context (characters). Since schema description coverage is 0%, this fully compensates and goes beyond the schema's bare property titles and defaults.

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 'Passages of a filing around every occurrence of a term, verbatim,' which clearly states the tool's function and output. This distinguishes it from sibling tools like get_filing_text or get_filings, which likely return full documents rather than targeted passages.

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

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

The description provides a concrete use case (finding a specific paragraph in a 10-K) and explains cost advantages over paging through the full document. It also clarifies that a no-match result means the term is absent from this document, not the company's filings. However, it does not explicitly name alternative tools or state when not to use this tool, which would make it a 5.

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

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

With no annotations, the description carries full burden and discloses key behaviors: returns multiple computed values, verdict types, handling of missing data via limitations, clamping of risk_pct, and stop/direction constraints. This is rich behavioral disclosure.

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

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

The description is dense but well-structured: purpose sentence, return summary, critical caveat, limitation note, then Args. Every sentence adds value and no information is repeated from 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?

With 8 parameters and an output schema, the description covers all essential aspects: return values, limit checks, verdict semantics, missing data handling, and parameter constraints. The context of the desk risk framework and sibling tools makes its role clear.

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 0% description coverage, but the Args section gives meaningful explanations for all parameters, including constraints (stop relative to entry), sources (ATR from get_technicals), and defaults (target omitted only if none given). This fully compensates for the schema gap.

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

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

The description clearly states the tool's function: sizing a trade against desk risk limits and returning a verdict. It distinguishes this from siblings by focusing on risk assessment rather than execution or data retrieval.

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

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

Explicitly instructs 'Never work a share count out yourself', positioning this tool as the authoritative sizing mechanism. The directive makes the intended use obvious and implies when not to use it (manual calculation).

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