LuxAlgo MCP

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

Annotations already cover readOnly/openWorld/non-destructive, so the bar is lower; the description adds genuinely new behavior context by noting the presets are precomputed nightly (staleness profile) and that each preset carries a plain-language definition. It omits any note on catalog size, pagination, or caching.

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 front-loaded sentences with no preamble; the purpose lands immediately and the edge_report linkage is last, where it belongs. The five-item family list ('gap fills, opening-range breakouts...') is illustrative but mildly expendable.

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

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

For a simple read-only catalog with 100% schema coverage and no output schema, the description adequately conveys what comes back (preset ids plus plain-language definitions) and why. It could go slightly further on return shape, but 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 100%, so both params are documented in the schema (including the category narrow filter and its parenthetical that results otherwise list all categories). The description adds no extra parameter meaning, so the baseline 3 applies.

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

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

States a specific resource ('the catalog of session-statistics questions the hosted store precomputes nightly') and its scope, with examples of preset families. It also distinguishes itself from sibling edge_report by declaring that it 'returns preset ids for edge_report', so an agent knows this is the enumerator feeding that consumer.

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 closing clause 'Returns preset ids for edge_report' makes the workflow role clear: call this to discover ids before invoking edge_report. It stops short of explicit when-not guidance or alternatives, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint, openWorldHint and non-destructive behavior, so safety is covered; the description goes further by disclosing the returned envelope (N, Wilson 95% CI, minimum-sample guards, first/second-half stability split, per-year counts, distribution for continuous outcomes, disclaimer). The 'Historical conditional frequencies, not predictions' caveat is genuinely useful interpretive context, though it omits failure modes and any rate/availability limits.

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

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

The core identity ('One precomputed session-statistics result') is front-loaded and the clause list maps to actual returned fields, so little is wasted. It is a single very dense sentence, though, and the trailing id-source sentence could be folded in without loss.

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

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

With no output schema, the description must carry return-value information, and it does so thoroughly, listing components of the result and a disclaiming caveat. What is missing is minor: no note on error conditions or sparse-data behavior beyond the mention of minimum-sample guards.

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

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

Schema description coverage is 100% across all three parameters, including the detailed third-person 'context' wording, so the schema carries the semantics. The description only echoes the 'see edge_presets / edge_symbols' pointers already present in the schema, adding no format or syntax detail beyond it.

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

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

The description names a specific verb-plus-resource (a precomputed session-statistics report) and pins the exact quantity returned: P(outcome | conditions) for a preset on a hosted symbol. It also implicitly separates itself from edge_presets/edge_symbols by casting them as id sources rather than result producers, so an agent can route without opening 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?

It tells the agent where the required ids come from ('Preset ids come from edge_presets; symbols from edge_symbols'), which is real prerequisite guidance. However, it never states when to prefer this tool over data-fetching siblings such as trackers_query or propfirms_* tools, nor any when-not condition, so usage is only implied.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, and the description is fully consistent with them. It adds real context beyond the annotations: the data provenance (open-source edge-stats engine over free market data) and a distinction between coverage metadata versus session statistics with sample sizes and confidence intervals. It does not disclose caching, pagination, or freshness guarantees beyond the build timestamp.

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, front-loaded with what the store covers and then the workflow routing, with no filler. The parenthetical about the edge-stats engine is dense but earns its place by clarifying the data source, though the sentence is long.

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 carries the burden of describing what is returned, and it does so by enumerating the coverage contents. Read-only annotations cover the safety profile, and the sequencing tells the agent how to proceed. Minor gaps remain (no mention of size, format, or pagination of the coverage listing).

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

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

Schema coverage is 100%, and the single 'context' parameter is a fully documented analytics-only bookkeeping field, so the schema already carries its semantics. The description adds nothing about parameters, which matches the baseline of 3 when the schema does the heavy lifting.

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

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

The description states what the hosted Edge Stats store covers (symbols, session calendars, coverage windows, session counts, last nightly build) and literally says 'Start here' for this tool, so an agent understands it exposes coverage metadata. It never uses a crisp verb like 'List' or 'Get', leaving the action implicit, but the resource and scope are unambiguous and it is clearly distinguishable from edge_presets and edge_report.

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

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

It gives explicit routing: 'Start here, then edge_presets for the questions you can ask, then edge_report for a result.' Both alternatives are named with the condition that selects each, so an agent knows which sibling to call at each step of the 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?

Goes well beyond the annotations by disclosing that identical fills are skipped as duplicates (explaining the idempotentHint mechanism), that trades are derived from fill sequences (long/short round trips, scale-ins, lone fill opens a position), that OAuth sign-in with a LuxAlgo account is required, and what mutations are impossible here.

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

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

Front-loaded with the action and account scope, and every clause carries a behavioral rule rather than filler. It is dense but slightly long, with several rules packed into run-on sentences that could be split for faster scanning.

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 covers the return contract (insert counts plus the trades the fills belong to, with keys for journal_update_trade), auth requirements, dedup behavior, and trade-derivation rules. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents accountId and each fill field. The description's notes ('Times are ISO 8601 instants with offset; fees are per fill') restate what the schema already says rather than adding format or constraint detail. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Log a trade by adding its fills') and immediately scopes the target accounts ('a `manual` or `import` journal account — never a broker-synced one'). This clearly separates it from siblings like journal_update_trade, journal_get_trade, and journal_list_trades.

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 (logging manual/import trades) and when-not (broker-synced accounts, correcting/removing fills — 'done in the app, not here'). It also names the follow-up tool (journal_update_trade via the returned keys) and the account source (journal_list_accounts).

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=true), so the bar is lower, and the description still adds real context: authentication via a LuxAlgo OAuth account, breakevens excluded from win-rate math, and a sensible all-time default chosen for sample size. It does not describe result volume/pagination for what could be nine groups of many symbols, which is the one remaining 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?

Front-loaded with what the tool returns and where the data comes from, then defaults, then sibling routing, then auth — a logical order. The nine-dimension enumeration and result-field list are long, but each clause carries information an agent would otherwise have to guess since there is no output 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 no output schema, the description compensates by naming the per-group metrics returned (trade count, wins, losses, net P&L, average net P&L, win rate) and the breakeven exclusion. Combined with the default-window rule, the narrowing parameters, the OAuth requirement, and sibling routing, 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 100%, so the baseline is 3, but the description adds semantics the schema lacks: the default window is all time and the reason for it, plus a stated preference for `range` or `from`/`to` when narrowing. The `accounts` and `context` parameters are left entirely to the schema, which documents them well.

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

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

States a specific verb and resource (P&L sourced from closed trades in a window, grouped nine ways by weekday, time of day, hold time, symbol, side, size, tag, rating, asset class) and explicitly contrasts itself with journal_overview as the headline-numbers tool. An agent can distinguish it from every sibling without opening a schema.

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

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

Gives an explicit selection rule ('the tool for "what am I good or bad at" questions') and names the alternative (journal_overview) for the headline case. It also states the default window and how to narrow it with `range` or `from`/`to`, so the when-to-use decision is fully specified.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds genuinely non-structured behavior: days are rendered in the journal timezone, cells are null for days with no trades, and a LuxAlgo OAuth sign-in is required. No pagination or rate-limit context, hence not a 5.

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

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

Front-loads the return shape before the operational notes, and every clause carries information (field list, timezone, default, alternative, auth). The opening sentence is dense with a long parenthetical field inventory, which slightly taxes readability.

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 carries the full burden of return-value explanation and does so thoroughly: day-cell fields, weekly aggregates, and monthly totals, plus the null convention and timezone. Auth requirement and the drill-down path are also covered, leaving nothing an agent needs to call it correctly.

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

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

Schema description coverage is 100%, so month format/default, context constraints, and accounts scoping are already documented in the schema. The description only echoes the current-month default and the journal timezone, adding no new parameter semantics. Baseline 3 applies.

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

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

States a specific resource and scope: one month of the P&L calendar, enumerating the cell-level and aggregate values returned (net/gross P&L, fees, counts, volume). It also names the sibling to use for finer granularity (journal_get_day), so an agent can distinguish it from journal_overview and journal_breakdown without opening a schema.

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

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

Gives explicit invocation guidance ("Omit `month` for the current month"), names the drill-down alternative (journal_get_day), and states the OAuth prerequisite. It stops short of explicit when-not-to-use conditions, e.g. preferring journal_overview or journal_breakdown for other grains.

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 read-only, non-destructive profile, so the bar is lower; the description still adds real context the annotations cannot: stats are null when nothing traded, trades are summaries rather than full records, and OAuth sign-in with a LuxAlgo account is required. It does not mention pagination or limits, but for a single-day read those are largely moot.

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

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

It is compact and front-loads the payload shape, which is the most decision-relevant information. The single dense paragraph is efficient, though the return-shape list and the date-format sentence slightly overlap 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?

With no output schema, the description carries the burden of describing return values and does so — stats, trade summaries, notes with ids, and the null case. It also flags the auth prerequisite, which is exactly the kind of precondition an agent needs before calling.

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

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

Schema description coverage is 100%, so the schema already fully documents `date`, `context`, and `accounts`, including the timezone and the 'omit for every account' semantics. The description restates the date format and timezone rather than adding new syntax or constraints, so the baseline of 3 is appropriate.

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

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

The description states exactly what a call returns for a single day: stats (null when nothing traded), trade summaries, and notes with their ids. It frames the scope as 'a single trading day', which contrasts cleanly with multi-day siblings like journal_calendar and journal_overview.

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

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

It gives a concrete usage scenario ('how did Tuesday go') and an explicit downstream routing rule, pointing to journal_update_note when note ids are the goal. It stops short of stating when-not-to-use this versus journal_get_trade or journal_search_notes, so it is clear context without full exclusion 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?

Beyond the annotations (readOnlyHint, destructiveHint, openWorldHint), the description discloses deployment requirements ('Requires signing in with a LuxAlgo account (OAuth)') and the full shape of the returned payload, including hidden fills and corrections. This is meaningful context the structured fields do not carry.

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

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

The lead clause 'One trade in full' front-loads the essential point, and the usage instruction is placed last where it is easy to act on. The middle enumeration of returned fields is dense but every element is a real differentiator, so little is wasted.

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

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

With no output schema, the description takes on the burden of explaining return values and does so in detail, while also covering prerequisites and auth. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, with the key parameter already documented as returned by journal_list_trades/journal_get_day/journal_search_notes/journal_add_trade and the 'Never construct one' rule. The description echoes the sourcing hint but adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('One trade in full') and enumerates exactly what that means — summary fields, fills, per-exit gross P&L, hidden fills, and annotations. This clearly separates it from the list-oriented siblings journal_list_trades and journal_get_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?

Explicitly says to use it after journal_list_trades or journal_get_day when the user asks about a specific trade, or before annotating it. That is clear contextual guidance, but it never states when not to use it or names a competing alternative tool to prefer.

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=true, so the safety profile is covered. The description adds real value beyond them: the auth requirement (LuxAlgo OAuth sign-in) and the meaning of an empty list ('no journal yet'), plus inline semantics for the `kind` values.

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

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

One paragraph, front-loaded with the resource and its fields before the critical 'Call this first' routing instruction. The field enumeration is somewhat long but justified because no output schema exists; every clause carries 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?

With no output schema, the description compensates by enumerating the returned fields (id, name, broker, kind, currency, balance, P&L method, sync, archived state, timeZone). It also covers auth, empty-state behavior, and cross-tool id dependencies, leaving nothing an agent needs missing.

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

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

Schema coverage is 100% and the single `context` parameter is a boilerplate analytics field already fully documented in the schema. The description adds no parameter-level syntax or format guidance, so the baseline 3 applies rather than a higher score.

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 ('The signed-in user's trade-journal accounts') and enumerates the returned fields, so the agent knows exactly what this returns. It is clearly distinguishable from siblings like journal_list_trades, journal_list_tags, and journal_overview.

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 says 'Call this first' and explains the dependency: other journal tools' `accounts` filter takes these ids and rejects unknown ones, and journal_add_trade needs a `manual` or `import` account. This is a genuine when-to-use and why-first directive that routes the agent correctly.

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

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new behavioral context: the authentication requirement (LuxAlgo account via OAuth) and the result ordering/count semantics. It stops short of disclosing result limits or pagination for a potentially long vocabulary.

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?

Four sentences, front-loaded with the resource and scope, then the workflow trigger, then the exclusion, then the prerequisite. Each sentence carries weight, though the auth sentence could have been folded in more tightly.

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 no output schema and only two parameters, the description covers what is returned, how it is ordered, its scope across accounts and archive state, the auth prerequisite, and a sibling-disambiguation rule. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so both parameters (context and accounts) are already fully documented, including the 'omit for every account, archived included / unknown ids rejected' semantics. The description reinforces the all-accounts default implicitly but adds no syntax or meaning beyond the schema, making the baseline 3 correct.

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 resource (the user's annotation vocabulary: tags, mistakes, playbook ids) and the exact scope (any trade, open or closed), plus the ordering and payload (most-used first with trade counts). It explicitly separates itself from per-trade tag data and from the similarly named sibling library_list_tags by scoping to journal annotations.

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 a clear triggering condition — call this before journal_update_trade so new annotations reuse the user's own vocabulary rather than minting duplicates — and a boundary rule ('Per-trade tags are on each trade summary, not here'). It does not name the specific alternative tool for per-trade tags (journal_get_trade/journal_list_trades), leaving that inference to the agent.

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

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

Annotations already declare readOnlyHint=true/destructiveHint=false, and the description adds substantial non-obvious behavior: keyset pagination requires identical args on the next call, trades missing the sort value come last in either order, netPnl is after fees vs grossPnl before, open positions are always listed despite the day window, and OAuth sign-in is required.

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 scope and return shape, then sorting, filtering, pagination and examples in a logical order; every sentence carries information. It is dense and long, with a long field enumeration, which costs a little readability, but no sentence is filler.

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

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

With no output schema, the description compensates by enumerating the summary fields and explicitly stating what is absent (fills, note text). Auth, pagination contract, filter semantics and defaults are all covered for a 12-parameter read tool.

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

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

Schema coverage is already 83%, yet the description still adds real meaning beyond the schema: sort names match response field names, symbol is the exception that defaults to asc, tie-break ordering, day keys are journal-timezone open-day keys, and tag matching is exact. The `cursor` must be paired with unchanged sort/order/filters.

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

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

States a specific verb+resource (list trade summaries) and immediately enumerates the returned fields, setting scope precisely. It explicitly distinguishes itself from journal_get_trade ("summaries carry no fills or note text") so an agent can tell the two apart without opening either schema.

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

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

Provides explicit when-to-use routing ("journal_get_trade with the `key` has those"), names sibling tools for preconditions (journal_list_tags, journal_list_accounts), and gives four concrete query recipes (biggest winners this month, worst by gross, longest holds). Nothing is left to inference.

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

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

Annotations already declare readOnly and non-destructive, and the description adds substantial behavior beyond them: close-day bucketing in the journal timezone, open positions counting toward any window reaching today, compare's 'previous' window semantics, and the meaning of null metrics (profitFactorIsInfinite). The OAuth requirement is also disclosed.

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

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

Front-loaded with purpose then progressively narrower detail on windowing and alternatives. The long metric enumeration is verbose but earns its place as de-facto return-value documentation in the absence of an output schema; still, it is a dense run-on that could be trimmed.

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

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

With no output schema, the description compensates by enumerating the returned metrics, the timezone/close-day logic, null-metric handling, window defaults, comparison behavior, and the auth prerequisite. An agent has everything needed to call and interpret the tool.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds runtime meaning the schema lacks: the 30-day default, that range:'all'/'from'/'to' widen the window, and the timezone/override behavior. It reinforces 'accounts' as the scope selector, though it doesn't detail every 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?

Opens with a specific verb+resource ('The journal dashboard in one call for a window') and enumerates exactly what it returns: performance metrics, Edge Score components, per-day P&L, equity curve, open positions, and the accounts/settings covered. It also explicitly names the siblings it is not (journal_breakdown, journal_list_trades), so an agent can distinguish it without reading 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?

States when to use alternatives: 'Use journal_breakdown for where the P&L comes from and journal_list_trades for the trades themselves.' Adds default behavior ('Defaults to the last 30 days'), how to widen ('range: all' or explicit from/to), and a prerequisite (LuxAlgo OAuth sign-in). Nothing about tool selection is left to inference.

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/destructiveHint=false, but the description adds meaningfully: OAuth sign-in requirement, newest-first ordering, keyset pagination via cursor/nextCursor, and the non-obvious drop-out behavior when filtering day notes by symbol. It stops short of return-format detail or rate limits, keeping it below a 5.

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

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

Dense but front-loaded — the stream/kinds structure comes first, then filters, then pagination, then auth. Every sentence carries information (probably more than a reader wants in one block), 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?

With no output schema, the description compensates by describing the return shape (a single stream split by kind, with ids for follow-up tools) and the auth prerequisite. Pagination and filter semantics are covered. Only minor gaps remain, such as default ordering fields or error behavior on unknown ids.

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 88% (baseline 3), and the description adds real semantic value beyond the schema: `symbol` only matches trade notes and causes day notes to be excluded, and the cursor must reuse identical arguments. This is behavioral meaning the 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 (Search) and resource (journal notes feed) and immediately disambiguates the two kinds it returns — `notes` (day notes) and `tradeNotes` — with the sibling tools used to edit each. An agent can distinguish this from journal_list_trades or journal_get_day without opening any schema.

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

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

Gives actionable context: 'Omit every filter for the latest notes', and explains that the symbol filter applies only to trade notes while day notes 'drop out'. It does not explicitly name a competing sibling (e.g. journal_list_trades) as the alternative when filtering by trade rather than note, so routing guidance is strong but not complete.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description supplies the specifics those hints cannot: the body is replaced whole (what is destroyed), the read-then-resend workaround for appending, the return value, and the OAuth sign-in requirement. This is meaningful context beyond the structured fields.

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 primary action, replacement semantics, and sibling exclusion are all front-loaded in the first two sentences, followed by the return value and reference links. No sentence is filler; each carries a distinct operational fact.

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 four-parameter mutation tool with no output schema, every piece an agent needs is present: id provenance, replacement-vs-append semantics, alternative tool routing, auth requirement, and the return shape. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real value by naming the tools that produce a valid noteId and by clarifying that 'date' relocates rather than edits the note. The full-replacement semantics for 'body' exceed what the schema's 'The full new text.' conveys.

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

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

The opening clause names a precise verb (replace), the resource (a day note's text) and a secondary effect (move it to another day), plus the key (note id). It explicitly distinguishes itself from the sibling journal_update_trade, so an agent can route correctly without reading either schema.

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

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

It states when to use it, where the noteId comes from (journal_get_day or journal_search_notes), and which sibling to use instead for trade notes (journal_update_trade). It also gives an explicit procedural rule for the append case, which is not inferable from the schema.

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

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

Annotations already flag destructiveHint=true and idempotentHint=true, and the description adds the crucial detail behind that: tags/mistakes replace the whole list, and null clears a field. It further discloses that P&L is derived from fills (not editable here), that the full updated trade is returned, and that OAuth sign-in with a LuxAlgo account is required.

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 purpose and field inventory, then usage rules, then side-effect boundaries. It is a dense single paragraph with no filler, though the clause stacking makes it slightly heavy to parse at a glance.

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

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

For a 14-parameter mutation tool with no output schema, the description covers the field set, the replace/clear semantics, the incremental alternatives, the auth requirement, and the return value ('the updated trade in full'). Nothing needed to call it correctly is missing.

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

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

Schema coverage is already 86%, so the baseline is 3, but the description adds real meaning: it explains that stopLoss/profitTarget are price levels and that the stop is the basis for realized R, and it clarifies the replace-vs-incremental semantics of the tag/mistake parameters beyond the per-field schema text.

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 ('Annotate a trade') and immediately scopes it to 'the user-owned fields only', enumerating them. This clearly separates it from journal_add_trade, journal_update_note, and journal_write_note among the siblings.

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

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

Explicitly routes between modes: bulk replacement fields vs. addTags/removeTags/addMistakes/removeMistakes for incremental edits, with the rationale ('without clobbering the rest') and a pointer to journal_list_tags for existing vocabulary. It also states what the tool does NOT affect (fills, prices, P&L).

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 cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantive behavior beyond them: notes are additive and never overwrite, the call returns the note with its id, and it requires OAuth sign-in with a LuxAlgo account. That is exactly the extra context an agent needs before invoking.

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 action and scope in the first clause, then routes to alternatives. It is dense but every clause carries information; the docs URL and OAuth note are mildly incidental but not padding.

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

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

There is no output schema, yet the description covers the return value ('the note with its id'), the write semantics, the auth prerequisite, and the sibling routing. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents date, body, and context, making 3 the baseline. The description adds real meaning for `date` by clarifying it may be any day, traded or not, and reiterates the journal-timezone YYYY-MM-DD format — useful for a date the agent might otherwise assume must correspond to a trade.

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 ('Add a new note to a trading day') plus the scope qualifier 'any day, traded or not', which an agent cannot infer from the name alone. It explicitly separates itself from journal_update_note and journal_update_trade's notes, so the sibling boundary 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?

Gives explicit when-to-use routing: this tool for creating, journal_update_note for changing an existing note, and journal_update_trade's notes for a note tied to a specific trade. It also states the non-exclusion ('days hold any number of notes, so this never overwrites'), removing the main ambiguity about whether a day can hold multiple notes.

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

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

Annotations already establish readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real value beyond that by describing the markdown payload structure and the hard requirement that the slug be exact, which is the main failure mode for this call.

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, zero filler: the first front-loads what the tool returns, the second front-loads the trigger condition and then the prerequisite. Every clause carries information an agent needs.

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

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

For a read-only lookup with no output schema, the description covers the return format, the content sections, the invocation precondition, and cross-references the discovery tools. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, and the schema itself documents both slug and context in detail. The description modestly reinforces this by flagging that the slug must be exact and naming the two tools that produce it, adding meaning beyond the schema's 'from search or list results'.

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 (explain/retrieve) and resource (a Library concept) and enumerates the exact content returned: definition, formula, how traders read it, and indicator implementations. This clearly separates it from siblings like library_get_indicator, library_get_family, and library_get_source_code.

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

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

Gives an explicit trigger condition ('Use for any "what is X / how does X work" question') and routes the agent to library_search or library_list_concepts for the required slug. It lacks an explicit statement of when another content tool would be the better pick, but the usage context is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), so the bar is lower. The description usefully adds return-shape information — that the result is markdown and contains both an overview and a full concept roster — which an agent cannot infer from 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?

Two compact sentences that front-load what the tool returns before giving usage ordering and triggers. No redundant restatement of the title or 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 no output schema, the description carries the burden of describing the return payload, and it does so ('hub page as markdown', 'overview plus concept roster'). It stops short of noting pagination/size limits on the roster, a minor gap for a list-bearing response.

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

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

Schema description coverage is 100% and the enum lists all valid family keys, so the schema already carries parameter meaning. The description adds essentially nothing beyond it ('SMC' and 'Wyckoff' are illustrative enum values, not new semantics), so the baseline 3 applies.

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

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

States a specific verb and resource ('a family's hub page as markdown') plus the exact payload ('the written overview ... plus its complete concept roster'). This clearly differentiates it from library_get_concept (single concept) and library_list_families (enumerating families).

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 ordering ('Use after library_list_families') and a user-intent trigger ('when the user asks about a whole area like SMC or Wyckoff'). It does not state when NOT to use it versus library_get_concept, but the trigger language implies the whole-area vs single-concept distinction.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value beyond that by disclosing the returned content, notably that source-code availability is reported here while the code itself lives behind another tool  that cross-tool distinction is the kind of behavior annotations cannot express.

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 resource and its payload, then the routing hint, with no filler sentences. The em-dash inventory is slightly dense but every listed field maps to something an agent may need to report back.

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?

No output schema exists, so the description usefully enumerates what comes back and points to the follow-up tool for code. It omits error/not-found behavior and whether the lookup is exact-slug only, but for a simple two-parameter read tool this is close to complete.

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

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

Schema description coverage is 100%, including a detailed contract for the 'context' parameter, so baseline 3 applies. The description only implies single-resource lookup via 'one indicator' and adds no slug format or usage detail beyond the schema's own example.

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 ('Details for one indicator') and enumerates the actual payload (behavior, reading guidance, family, concept links, preview image, code availability). It also names the sibling library_get_source_code, so an agent can distinguish retrieval of metadata from retrieval of code without opening either schema.

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

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

Gives an explicit trigger ('Use when the user asks about a specific indicator') and routes to library_get_source_code for the code itself. It does not state when NOT to use it (e.g., to browse many indicators, where library_list_indicators or library_search would apply), so it falls short of full when/when-not 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?

Goes well beyond the annotations: discloses that signed-out users may receive truncated source signalled by `complete: false` plus line counts, that signing in (free tier included) returns the full source, and that `chart_url` always works. That is exactly the kind of auth/partial-result behavior an agent needs and cannot get from readOnlyHint alone.

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

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

Three sentences, front-loaded with purpose then the routing rule then the truncation caveat — no filler. Slightly dense with a trademark symbol and parenthetical detail, but every sentence carries actionable 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?

Despite no output schema, the description names the key return signals (`complete`, line counts, `chart_url`) and the auth condition that changes results. Nothing an agent needs in order to call this correctly or interpret a partial answer 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 100%, so slug and context are already documented in the schema; the description adds no parameter-level format or constraint detail. Baseline 3 is appropriate when the schema does the work.

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 ('The Pine Script® source code of a Library indicator') and immediately distinguishes itself from the sibling library_get_indicator. An agent knows exactly what this returns without reading the schema.

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

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

Explicitly states the selection condition — 'call it only when the user wants the code itself' — and explains why it is separate from library_get_indicator (sources are long). This is a clear when-to-use plus a named alternative, with an implicit when-not-to-use.

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=true, so the safety profile is covered. The description adds pagination and single-family scoping, but says nothing about return shape, page-size bounds, or total-count behavior. Annotations carry most of the behavioral weight, so a 3 is appropriate.

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?

A single dense sentence that front-loads what the tool returns and its scope before listing the routing alternatives. No filler or restatement of the title.

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 no output schema, the description covers purpose, alternative routes, pagination, and family filtering, and even hints at returned slugs. It stops short of describing item shape or how many results a page yields, which is the only thing an agent might still wonder about.

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 75% and the family enum is fully enumerated in the schema; the description still adds meaning by framing the family argument as an optional single-family restriction and by flagging pagination. It does not explain page/page_size defaults or the analytics-only context parameter, leaving a small gap.

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

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

States a specific verb and resource ('Browse every trading and technical-analysis concept in the Library') plus its two scoping traits: paginated and optionally a single family. This is clearly separable from library_search (keyword) and library_get_concept (single fetch) named in the same sentence.

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 cases ('enumerate a topic area', 'find slugs for library_get_concept and the concept filter of library_list_indicators') and an explicit when-not with the alternative ('for keyword lookup prefer library_search'). The routing decision is fully resolvable without opening schemas.

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=true, so the safety profile is covered. The description adds useful content-level detail (concept counts and hub links are returned), which is more than the annotations convey, though it omits return format specifics.

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

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

Two tight sentences: the resource definition comes first, followed by the usage cue. No filler, every clause carries 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 small read-only taxonomy listing with full schema coverage and annotations covering safety, nothing an agent needs to select or invoke it is missing. No output schema means return contents are reasonably summarized in the 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 100% and the single 'context' parameter is fully documented as an analytics field, so the schema does the work. The description adds no parameter-specific semantics, which is the expected baseline here.

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

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

States a specific verb+resource ('List' the 'families') and defines the scope precisely as the top-level taxonomy with 17 families, plus what each entry contains (concept counts, hub links). This distinguishes it from siblings like library_list_concepts and library_get_family, which operate at a deeper level.

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 frames itself as 'the natural first call for orientation', giving clear usage context. It does not name a specific alternative or an exclusion condition, but the entry-point framing 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 declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so safety is covered. The description adds real behavioral detail beyond that — default sort is newest-first, sorting is server-side, and filters compose over family/concept/platform/tier — though it doesn't describe pagination rollout or result 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 with the core action and default ordering, then use cases, then the alternative. Dense but every clause carries information; the trailing 'for keyword discovery prefer library_search' is well-placed. Minor length density keeps it below a 5.

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

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

A 10-parameter list tool with no output schema is well served here: filtering axes, sorting default, and sibling dependencies are all covered. The only gap is that it never characterizes the returned page (fields, pagination totals) or result-shape expectations, which matters somewhat without an output schema.

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

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

With 90% schema coverage the schema already documents most parameters, so the baseline is 3. The description adds genuine provenance semantics the schema cannot: family keys come from library_list_families, concept slugs from library_list_concepts/library_search, and concept filtering means 'that concept's implementations'. Page, page_size, direction, and text remain unaddressed by prose.

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

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

States a specific verb and resource — browsing the indicator catalog with filters and server-side sorting — and immediately contrasts itself with library_search for keyword discovery. An agent can distinguish it from library_list_concepts, library_list_families, and library_search purely from 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?

Names explicit when-to-use scenarios ('latest indicators', 'everything in the volatility family', 'indicators implementing liquidity sweeps') and an explicit when-not with the alternative to pick instead (library_search for keyword discovery). The dependency keys are routed to the correct 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 declare readOnlyHint/openWorldHint/destructiveHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: alias-aware matching ('stochastics' finds Stochastic Oscillator) and the shape of results (slugs for the get tools plus canonical URLs for citation). It omits rate limits or result-count behavior beyond the schema's limit field.

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 tight sentences, front-loaded with what the tool searches and immediately followed by scope, then the routing signal. 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 read-only search tool with a fully documented schema and annotations covering safety, the description supplies the missing output-shape information (slugs and canonical URLs) in lieu of an output schema, so an agent knows both how to call it and what it will get back.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the query semantics and the concepts/indicators split, but its alias example ('stochastics') is already present in the schema's query description, so it adds little beyond what the structured fields provide.

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

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

Specific verb (Search) plus resource (LuxAlgo Library) plus concrete scope: 800+ concepts and 800+ indicators. It is clearly distinguishable from siblings library_get_concept / library_list_concepts because it positions itself as the query entry point rather than a fetch or browse 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?

'Start here whenever you have a name, informal term, or topic' gives an explicit trigger condition, and 'results carry slugs for the get tools' routes the agent to the follow-on tools. It stops short of naming the alternatives (library_get_concept, library_list_concepts) or stating when NOT to use it, so it is clear context without full exclusion 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, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: it is scoped to 'the signed-in user' and requires OAuth authentication. Return contents are summarized though no 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?

Two sentences, front-loaded with what the tool returns before the usage guidance and the auth requirement. Every clause carries information; no waste.

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

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

For a single-parameter read tool the description covers what is returned, when to call it, and the auth requirement. With annotations covering safety and no output schema to explain, nothing an agent needs is missing.

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

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

There is only one parameter (context) and schema description coverage is 100%, so the schema fully documents it with its own detailed guidance. The description adds nothing about the parameter, which is the correct baseline when the schema does the heavy lifting.

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

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

The description names the exact resource (the signed-in user's LuxAlgo account) and enumerates its contents (plan tier, entitlements, profile basics). It clearly distinguishes this account-lookup tool from the journal/library/propfirms siblings. It lacks an explicit verb, but the purpose is unambiguous.

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

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

It gives concrete triggers: 'use it to tailor answers to what the user's plan actually allows' and 'when the user asks what plan they are on.' It also states the prerequisite (sign in with a LuxAlgo account / OAuth). No alternative tool is named, but none of the siblings overlap this function.

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 readOnly/destructive/openWorld annotations it discloses genuinely useful behavior: data is fetched live from a keyless public API, inferred semantics are named in `inferredFields`/`provenance`, and challenges whose loss rules cannot be established are refused rather than guessed. It also flags `flagsNotSimulated` as material caveats and stresses the firm page is authoritative. That is far more than the annotations carry.

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

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

The purpose is front-loaded in the first clause, which is good. However the body is an extremely long, heavily parenthesized enumeration of rule semantics that is difficult to scan; much of it reads like output documentation rather than selection guidance. Some of it is justified because no output schema exists, but the density harms usability.

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

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

For a complex, schema-light tool with no output schema, the description covers source and provenance, unit conventions (percent vs fraction), inference disclosure, refusal behavior, and how the result feeds the simulation tools. Nothing an agent needs in order to call it and interpret the result is missing.

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

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

All three parameters are fully described in the schema (100% coverage), including the analytics-only `context` field with a worked example, so the schema does the heavy lifting. The description adds a units convention for rule fields and winRate, but that concerns the result shape rather than the inputs. Baseline 3 is appropriate.

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

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

The opening sentence names a specific verb and resource ('Fetch one directory challenge's complete ruleset (ChallengeSpec)') and scopes it to the live LuxAlgo directory. It explicitly distinguishes itself from siblings, noting that this returns the simulatable encoding while propfirms_get and propfirms_search_challenges serve the raw directory listing. An agent can route correctly without opening any schema.

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

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

It explains the intended workflow clearly: the returned `challenge` object is exactly what the simulation tools accept as inline `spec`, so it can be copied, mutated and re-simulated. The closing NOTE names the alternative tools for the broader directory view. It lacks an explicit 'do not use when...' exclusion, but the routing context is strong.

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

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

Annotations only cover read-only/destructive safety, but the description discloses far more: determinism (byte-identical results per seed), units conventions, what is and isn't simulated (consistency rules and payout gating ARE; flagsNotSimulated are not), and the material assumptions/disclaimer. It even prescribes how results must be presented. Rich behavioral context 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?

Purpose and scope are front-loaded, but the description is unusually long and its UNITS and DETERMINISM blocks largely restate schema field descriptions. Several sentences earn their place (flags, presentation guidance), but the overall bulk is heavier than needed.

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

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

For a 16-parameter, high-complexity simulation tool with no output schema, the description enumerates the returned row fields, explains the flags/disclaimer obligation, and covers determinism and horizon scaling. An agent has everything required to call it and interpret the result responsibly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds interpretive value: it flags winRate as a FRACTION (not percent) and 'the most impactful input', restates the percent-mode risk convention, and explains seed/paths reporting for reproducibility. Useful emphasis, though much of it echoes the schema.

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

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

States a precise verb and resource ('simulate the SAME trader across several challenges') plus the output shape (one row per challenge sorted by EV). Explicitly distinguishes itself from a ranking tool and from propfirms_simulate, so an agent can identify its niche without opening the schema.

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

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

Gives clear use context ('2+ for meaningful comparison'), an explicit when-not ('THIS IS NOT A RANKING... implies no endorsement'), and a named alternative ('For full per-challenge distributions run propfirms_simulate on the interesting rows'). The routing decision is fully stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely non-obvious behavior: null/uncaptured fields are omitted rather than returned as nulls, and challenge objects link to firm-level offers through offerIds. It does not mention rate limits or pagination, but with no output schema this is a solid disclosure of 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 with the payload contents before routing and format caveats, and every clause carries information. It is dense – four ideas packed into two long sentences – but nothing is redundant with the title or 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 no output schema, the description must convey the return shape, and it does: the section list, the offerIds cross-reference between challenges and offers, and the null-omission rule. An agent can predict what it gets back and where to look next; only enumeration bounds/pagination remain unspecified.

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

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

Schema coverage is 100% and the propfirmId slug format ('ftmo') plus the analytics-only context parameter are fully documented in the schema. The description's 'Find slugs with propfirms_search' adds a small navigation hint but no new meaning about the parameters themselves, so the baseline 3 applies.

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

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

States a specific verb and resource ('One prop firm's full dossier by slug') and enumerates the payload sections (profile, challenges, offers, overview), which is far more precise than the title alone. It also distinguishes itself from propfirms_search, the sibling that resolves the slug.

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

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

Explicitly routes the agent: use propfirms_search to find slugs, and propfirms_pass_rates for simulated pass odds on this firm's challenges. Both the input-discovery path and the analytical alternative are named with the condition that selects them.

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

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

Annotations only declare readOnlyHint/openWorldHint/destructiveHint; the description goes far beyond by disclosing the live keyless external data source, that inferred rule semantics are flagged in `inferredFields` with provenance 'directory+inferred', that unencodable challenges are refused into `notSimulatable` rather than guessed, and that the listing is explicitly non-endorsing and unranked.

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 scope and provenance lead are front-loaded and valuable, but the text is very long and repeats itself: 'Challenges whose loss-rule semantics cannot be established are listed under notSimulatable' is restated almost verbatim later as 'Challenges whose loss rules cannot be established are refused as not simulatable rather than guessed.' The provenance rule is likewise stated twice, diluting an otherwise useful definition.

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 correctly compensates by naming the returned fields (challengeId, display name, account size, currency, price, provenance) and the notSimulatable branch. It omits any mention of the required `context` argument, but otherwise an agent has enough to call and interpret the tool.

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

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

Schema coverage is 100% and both parameters (context, productType) are fully documented in the schema with an example for `context`. The description adds nothing about either parameter, so the baseline 3 for schema-does-the-work applies.

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

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

The description opens with a specific verb+resource ('List the prop firms ... together with every simulatable challenge') and enumerates the returned fields. It explicitly distinguishes itself from propfirms_search / propfirms_search_challenges / propfirms_search_offers, so an agent can route without opening sibling 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?

It gives an explicit ordering directive ('Call this first to discover the firmId + challengeId pairs accepted by propfirms_challenge_rules, propfirms_simulate, propfirms_optimal_risk, propfirms_compare and propfirms_simulate_trades') and names the alternative tools for the broader directory. Both when-to-use and when-to-use-something-else are covered.

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

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

Beyond the annotations (readOnlyHint/openWorldHint), the description discloses rich behavior: common random numbers make the argmax signal not noise, results are byte-identical for the same seed, cost scales with grid size (~30 points at 10,000 paths ≈ 10 seconds), and every result carries assumptions.flags and a disclaimer. This is exactly the extra context annotations cannot provide.

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

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

It is long but intentionally front-loaded, opening with the core action and the two optima before the caveats. Some material (determinism/seed, disclaimer) is restated and could be tightened, but given 20 parameters and a nested spec, most sentences earn their place.

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

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

For a complex tool with no output schema and a deeply nested spec, the description is complete: it names the result fields, explains the divergence concept, covers units, determinism, cost, and the assumption-flag reporting obligation. An agent has everything needed to invoke and report 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 100%, so the baseline is 3, but the description adds interpretive value: it clarifies that grid units follow riskMode (percent units by default 0.1–3, currency for 'fixed-amount'), and prominently warns that winRate is a fraction while percent fields are in percent units. That unit disambiguation meaningfully reduces misconfiguration 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 states a specific verb and resource: 'Sweep risk-per-trade over a grid, run the full journey simulation at every point, and report two optima.' It names the exact outputs (bestByPassProbability, bestByEv) and the core insight (divergence between them), so an agent immediately knows this is a two-optima sweep rather than a single-run simulation.

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

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

It gives clear operating guidance: 'use fewer paths or a coarser grid for a first pass, then refine around the optima,' 'Parametric trader only,' and 'Never present one number as THE optimal risk.' It does not explicitly name sibling tools (e.g. propfirms_simulate) as alternatives, so routing is implied rather than stated, keeping it below 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?

Beyond the readOnly/openWorld annotations, it discloses behavioral traits the annotations cannot convey: deterministic per ruleset, cached and cheap to call, fixed seed/path count, and the exact shape of returned odds including provenance flags. It also tells the agent it must relay inferred fields, a real operational constraint.

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

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

Purpose and routing are front-loaded, but the middle enumerates many return fields and engine constants, making it a dense wall of text. Most sentences earn their place, though the return-value list could be trimmed since it borders on 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?

With no output schema, the description carries the full burden of explaining returns, and it does so (pass probability, 95% CI, P(funded), expected attempts/cost, EV, blowup probability, provenance). Combined with the sibling routing, an agent has everything needed to call and interpret it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds that a challengeId can be omitted to compute every simulatable challenge and clarifies the archetype semantics (developing 45% / consistent 48% / proven edge 52%). That is meaningful supplementary context 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 a specific verb+resource ('Reference challenge pass rates computed live from the directory's encoded rules') and pins down scope per challenge and per archetype, naming the concrete engine parameters (seed 42, 10,000 paths). It clearly distinguishes itself from propfirms_simulate and propfirms_simulate_trades as reference rather than personal odds.

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

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

It gives explicit when/when-not routing: 'These are REFERENCE odds for orientation and comparison, not the user's personal odds: for their own statistics use propfirms_simulate ... or propfirms_simulate_trades'. It also warns the tool is 'Not a ranking' and that a firm's page is authoritative, adding a provenance caveat to relay inferred fields.

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 read-only, non-destructive, open-world, but the description adds real behavioral context beyond them: the OR-across-children / AND-across-filters matching rule, that uncaptured (null) fields are omitted, and that nested challenges reference offers via offerIds. It also frames the tool as directory data, not outcomes.

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

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

Purpose and matching semantics are front-loaded, and despite its length nearly every clause carries operative information (matching rule, include behavior, sibling routing). It is dense rather than padded, though the offerIds/overview sentence could be tightened slightly.

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 54-parameter, no-output-schema tool this is close to complete: it explains filter combination, include nesting, null omission, and where to go for results it does not return. Minor gap is no explicit mention of pagination defaults (pageIndex/pageQuantity), though those are self-documented in the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns above that by explaining cross-parameter semantics the schema cannot — how firm, challenge, and offer filters combine, and that a firm matches when at least one child matches all filters. It groups the 54 parameters into firm/challenge/offer families, aiding navigation of a large flat 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 LuxAlgo's prop-firm catalog') and immediately defines the domain ('proprietary trading firms offering funded accounts'). It also distinguishes itself from the sibling propfirms_get by routing single-firm lookups there, so an agent can pick the right tool without opening either schema.

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

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

Explicitly covers when-to-use ('omit every filter to list all firms'), which sibling to prefer for one firm's dossier (propfirms_get), and which siblings to chain for outcome data (propfirms_pass_rates, propfirms_simulate). The alternative-routing guidance is unusually thorough.

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/destructiveHint/openWorldHint, so the safety profile is covered. The description still adds non-obvious behavior: uncaptured (null) rule fields are omitted from results and never match filters, and include=['offers'] yields a deduplicated top-level offers list with per-challenge offerIds. Return format specifics (pagination shape) remain unstated, keeping this at a 4 rather than 5.

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

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

Front-loaded with the core action and scope, then progressively adds filtering scope, id-routing, include behavior, and sibling routing. Every sentence carries distinct information; nothing is redundant with the schema or annotations.

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

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

For a 36-parameter tool with 100% schema coverage and read-only annotations but no output schema, the description does the heavy lifting on routing and the offers/null-filter contract. It reasonably states the tool returns rules and terms rather than outcomes. Missing only explicit return-shape/pagination detail.

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

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

Schema description coverage is 100%, so the baseline is 3. The description lifts this by clarifying the include=['offers'] contract (deduplicated top-level list, offerIds cross-reference, firm-wide offers included) and the null-field filter behavior, which the schema's one-line parameter notes do not convey. Minor added value beyond schema, hence 4.

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

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

States a specific verb+resource ("Search funded-account challenges across all visible prop firms") and immediately names the dimension of differentiation (rules/terms vs. outcomes). Siblings propfirms_search, propfirms_search_offers, propfirms_compare are distinguishable because this tool returns challenge rule/term records specifically.

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

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

Explicit routing: "Pass propfirmId to list one firm's challenges, or challengeId to fetch specific ones," and it names the exact alternatives for downstream steps (propfirms_simulate, propfirms_pass_rates, propfirms_validate_strategy) with the condition that selects each. When-to-use and when-to-go-elsewhere are both covered.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety bar is low; the description adds meaningful behavior by stating the live-offers default and enumerating the payload each offer carries (promo code, discount, end date, affiliate link). With no output schema, that return-field disclosure is genuinely useful. It does not cover pagination limits, but the schema does.

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 densely informative sentences with the default behavior front-loaded and no filler. Slightly compressed—the challengeId clause is a bit parenthetical—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?

For an 18-parameter search with no output schema, the description covers intent, default scope, key routing filters, and return fields, which is close to complete. Remaining gaps (sorting, paging, the expire/inactive toggles) are handled adequately by the schema descriptions.

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

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

Schema description coverage is 100%, so the schema already documents all 18 parameters, establishing a baseline of 3. The description's mention of propfirmId and challengeId filtering largely restates what the schema says (including the firm-wide offer inclusion note), adding little beyond it.

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

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

The description states a specific verb and resource ("Search promotional offers (discounts and promo codes) across prop firms") and scopes it to live offers by default. An agent can distinguish this from siblings like propfirms_search_challenges or propfirms_search, which cover different resources.

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 the default behavior (live/active, unexpired offers only) and how two key filters route the query (propfirmId narrows to one firm; challengeId resolves applicable offers including firm-wide ones). It stops short of naming alternatives such as propfirms_search_challenges or stating when-not to use this tool, so it is solid context without 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?

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description goes well beyond that, disclosing determinism (seed reproduces byte-identical results), what is actually simulated vs merely flagged (consistency stop-rule, withdrawal model, funded consistency approximation), required surfacing of assumption flags/disclaimer, and data provenance (live LuxAlgo directory, inferredFields, refusal of un-simulatable challenges). This is unusually rich, though some claims (return shape) sit in description rather than a 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?

Purpose and scope are front-loaded, but the description is very long (roughly 700 words) and repeats material already carried verbatim by the schema — the units conventions, the seed/determinism note, the winRate warning, and the directory-vs-spec rule all appear in both places. Much earns its place; enough is redundant that it is not tight.

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 19-parameter tool with nested spec objects and no output schema, the description fills the gap by enumerating the returned SimResult fields (perAttempt, journey, funded, ev, drawdown, assumptions) and explaining payout gating vs getting funded. Nothing an agent needs to call it correctly or interpret results 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 100%, so per-parameter meanings are already documented and the baseline is 3. The description still adds cross-cutting value the schema cannot: the flattened parametric design rationale, the recurring UNITS convention (every *Pct and percent-mode risk is percent units; winRate alone is a fraction), and the exactly-one-of requirement for firmId/spec identification.

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

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

The opening sentence names a specific verb and resource ('Monte Carlo-simulate a trader ... through a prop-firm challenge') and enumerates the concrete questions answered (pass probability, attempts/cost, EV, which rule kills attempts). It explicitly contrasts itself with the sibling propfirms_simulate_trades, so an agent can route between them without opening either schema.

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

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

It states the two mutually exclusive identification paths (directory firmId+challengeId vs full inline spec), that exactly one is required, and the network/offline implication of each. It also names the discovery sibling (propfirms_list_simulatable) and the condition for preferring propfirms_simulate_trades (raw trade series, streak preservation).

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

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

Annotations only declare readOnly/openWorld/non-destructive; the description adds substantial behavior beyond that: determinism via `seed` (byte-identical reruns), the double-run with shared seed for newsFilter, the audit-risk warning that a 'high' overlap verdict may cause firms to refuse payouts, verbatim-relay caveats, assumption flags that make real odds worse than simulated, and the consistency/withdrawal simulation model. This is unusually 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?

It is front-loaded correctly (purpose, then why, then sibling routing, then input modes), but the SIMULATED RULES and UNITS paragraphs largely repeat content already present in the per-parameter schema descriptions, and the whole block runs far longer than the agent needs to select and call the tool. Dense but not concise.

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

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

With 21 parameters, deep nesting, no output schema, and two required inputs, the description carries the full burden and meets it: it describes the returned SimResult, structuredContent.newsComparison and structuredContent.portfolioOverlap, histogram default-off behavior, and the reporting obligations (seed, paths, flags, disclaimer). Nothing material for correct invocation is left unstated.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds cross-parameter semantics the schema does not: the exactly-one-of constraint across the four series inputs, the 10-trade minimum / 100+ recommendation, the PERCENT-vs-FRACTION unit convention for all *Pct fields vs winRate, and the rSource inference behavior of importRisk. The Units and Simulated Rules paragraphs partially restate per-parameter descriptions, keeping it below 5.

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 names a specific verb and resource ('Simulate a challenge by resampling the trader's OWN R-multiple trade series with a stationary block bootstrap') and explicitly contrasts its method with the parametric alternative. It names the sibling it is not ('Use propfirms_simulate when only summary stats are available; use this whenever the actual trades are'), so an agent can route without opening either schema.

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

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

It states exactly when to use this vs the alternative, and enumerates the mutually-exclusive input modes (rSeries / rSeriesText / tradeLogText / tradeLogTexts) with 'exactly one of the four, at least 10 trades'. It also gates the news-filter and portfolio behaviors on timestamped inputs, giving conditional when-to-use guidance throughout.

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

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

Annotations only declare readOnly/openWorld/non-destructive, but the description discloses determinism per seed, one full simulation per challenge (cost scales with scope), a hard 40-challenge refusal, fees taken from listed prices with discounts NOT applied, flags making numbers optimistic, and honest exclusion of unencodable challenges. This is substantial behavioral context well 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?

Front-loaded with the core question and scope, but it is a very long run-on paragraph packing in assumptions, honesty framing, and caveats. Every clause carries content, yet the wall-of-text form hurts scannability for a 25-parameter tool.

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

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

No output schema exists, and the description compensates by enumerating the returned fields (pass probability with 95% CI, P(funded), expected attempts/cost, EV, P(EV>0), assumption flags). For a high-complexity screening tool it is complete enough 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 coverage is 100% and each parameter is already documented, so the baseline is 3. The description still adds interpretive value: it explains the two strategy-input modes and that rSeries is preferred, clarifies the minPassPerAttempt bar default and the 'always state the bar' convention, and notes that numbers move with risk sizing.

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

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

States a specific verb+resource+scope ('simulate the given strategy through every simulatable challenge in the live directory') and frames it as answering a concrete question. It is clearly distinguishable from single-challenge siblings like propfirms_simulate and propfirms_optimal_risk, which it explicitly names.

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 strong routing guidance: 'sweep one challenge with propfirms_optimal_risk afterwards', refuses scopes above 40 challenges ('narrow the scope instead'), and points to directory siblings (propfirms_search_challenges/get/search_offers). It stops short of stating when NOT to use this versus propfirms_simulate or simulate_trades, so it is clear context rather than a full when/when-not map.

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

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

Annotations already cover the safety profile (readOnly, non-destructive, open-world), so the bar is lower. The description adds real behavioral context: the dumps are CC0, the listing returns row count, freshness, year coverage (live tree vs deep-history), and ticker-searchability, and the dataset variant surfaces caveats, per-year coverage and source health.

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 tightly packed sentences; the scope statement is front-loaded and the workflow instruction comes last where it belongs. The 18-item dataset enumeration is long but earns its place by decoding the enum, so waste is minimal.

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?

No output schema exists, so the description must carry return-value information — and it does, listing the fields of both the summary and the per-dataset detailed view, plus dump URLs. The required context parameter's constraints are fully handled in the schema, so nothing essential is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds meaning beyond the schema: it maps the opaque enum slugs to human-readable sources (cot-reports → CFTC positioning, short-volume → FINRA short-sale volume, fed-communications → Federal Reserve communications) and explains what the dataset-specific view returns.

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?

Names a concrete verb+resource (the Market Trackers catalog / listing every published dataset) and enumerates the exact domain content, so the agent knows precisely what it retrieves. It is unmistakably distinct from trackers_latest, trackers_query, and trackers_ticker.

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

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

Explicitly routes the agent: 'Pass dataset for the full field roster... read it before composing trackers_query filters.' That gives a clear when-to-call and names the primary alternative (trackers_query). It stops short of stating when *not* to use it or how it relates to trackers_latest/trackers_ticker.

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=true), and the description adds genuinely new context: the data is the dumps' latest.json, scoped to a single ingestion day, and is unavailable for snapshot-only bulk datasets. It does not mention rate limits or result freshness caveats, but the added availability constraint is substantive.

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

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

Three sentences, front-loaded with the core definition and the availability caveat, with zero filler. The parenthetical naming latest.json is dense but earns its place by grounding the data source.

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

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

For an 8-parameter read tool with no output schema, the description conveys the data source, the scoping semantics, the filtering options, and the dataset limitation. It stops short of describing return shape or paging behavior, but annotations plus full schema coverage carry most of the remaining burden.

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

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

Schema coverage is 100%, so all eight parameters are already documented in the schema, making 3 the baseline. The description adds only marginal meaning — that ticker/text optionally narrow the newest-day scope and that textPaths live in trackers_datasets — without explaining sort/limit/offset/where beyond what the schema states.

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 precise verb+resource+scope: the newest ingestion day's rows added to one dataset by the last daily publish, sourced from latest.json. It explicitly distinguishes itself from the sibling trackers_query for the cases where it does not apply, so an agent can route without opening either schema.

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

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

It gives both when-to-use ('the cheapest way to see what is new: today's insider filings, this week's congressional disclosures, the latest lobbying registrations') and when-not ('Not available for snapshot-only bulk datasets (patents)'), naming the alternative tool to use instead. Nothing is left to inference.

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 readOnlyHint/openWorldHint/destructiveHint already covering the safety profile, the description adds substantial non-obvious behavior: data comes from year-sharded CC0 dumps, the default year is the newest with data, deep-history years are tens of MB compressed, the tool self-limits via a byte budget and returns narrowing instructions on refusal, and every row carries provenance.sourceUrl. That is real operational context an agent cannot get from 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 purpose, the sharding/budget mechanics, and the examples are ordered sensibly with the core search capability front-loaded. The examples sentence is long and packs three scenarios into one breath, but each clause adds routing value rather than filler.

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

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

For an 11-parameter tool with no output schema, the description covers defaults, cost/limits, refusal behavior, and provenance fields well. It stops short of describing the row shape beyond provenance.sourceUrl, which is a minor gap given there is no output schema to lean on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes beyond the schema by tying parameters together in end-to-end examples (dataset + ticker + years + where for insider purchases; dataset + text for lobbying) and by stating the default years behavior and the prefer-one-year-at-a-time rule for `years`.

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 precise verb+resource+capability statement: 'Search one Market Trackers dataset by ticker, free text, exact field values, and event-date range, with paging and newest/oldest ordering.' That cleanly separates it from a listing tool, but it never names the obvious siblings (trackers_datasets for discovery, trackers_latest, trackers_ticker), so the agent must infer the routing.

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 concrete: it explains the year-sharding model, that the default is the newest year with data, that deep-history years should be read 'one or two at a time', and it gives three worked examples mapping a user goal to dataset/ticker/years/where/text. What it lacks is explicit exclusion or alternative routing (when to prefer trackers_latest or trackers_ticker instead).

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail: per-dataset match counts plus newest rows, and the fact that some archives are returned as 'skipped' rather than fetched inline — useful for anticipating truncated results.

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

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

Front-loaded with the core purpose, then the dataset enumeration and the skipped-year caveat. The long list of datasets is informative rather than filler, though it makes the entry denser than strictly necessary.

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

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

For a multi-dataset fan-out tool with no output schema and no nested objects, the description covers what comes back (counts + newest rows, skipped archives) and how to follow up. It omits anything about ordering/volume limits of the aggregate response, but nothing essential for a correct call is missing.

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

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

Schema description coverage is 100%, and the schema already documents the year default (current year), limit default (5 newest rows per dataset), ticker format, and the context field. The description restates the year scope and the 'newest rows' semantics without adding formats or edge-case syntax, so baseline 3 applies.

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

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

States a specific verb+resource+scope ('one ticker across every ticker-bearing Market Trackers dataset for one year') and enumerates the covered dataset families, so an agent knows exactly what it returns. It also names a sibling (trackers_query) as the follow-up for large archive years, distinguishing it from the other trackers_* 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?

Gives clear context (single ticker across all datasets for one year, default current year) and an explicit alternative path: deep-history years too large for one fan-out are listed under 'skipped' with the trackers_query call that reads them. It does not, however, state when to prefer trackers_latest or trackers_datasets over this tool.

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