luxalgo-mcp-server

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds useful behavioral context beyond that: the data is precomputed nightly, the catalog is framed in plain language, and the output is preset ids. There is no contradiction with 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?

Three sentences, all informative and free of filler. It front-loads the core concept, gives illustrative examples, and ends with the actionable output. Every sentence earns its place without being overly terse.

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

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

For a simple read-only list tool, the description is complete: it explains what the preset catalog is, what kind of information each preset contains, and what the tool returns. The absence of an output schema is compensated by 'returns preset ids for edge_report' and the description of each preset's plain-language meaning.

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 parameters are already documented. The description does not add meaning about the optional category parameter or the required context parameter, but it doesn't need to because the schema covers them. This matches the baseline for high schema coverage.

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

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

The description uses a specific verb ('list'/'returns'), clearly identifies the resource as Edge Stats report presets, and distinguishes the tool from edge_report by noting it returns preset ids for that sibling tool. The examples of preset types ('gap fills, opening-range breakouts') make the tool's purpose concrete and unambiguous.

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

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

The description makes the use context clear: it is a catalog of precomputed session-statistics presets and returns ids intended for edge_report. It stops short of explicitly stating when not to use this tool versus alternatives, but the tie to edge_report gives an agent enough context to select it appropriately.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description reveals substantial behavioral detail: the report includes N, a Wilson 95% confidence interval, minimum-sample guards, a first-half/second-half stability split, per-year counts, and a disclaimer. It also clarifies that results are historical conditional frequencies, not predictions. This is precisely the kind of context agents need to interpret outputs correctly.

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

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

The description is dense but purposeful: it opens with the core result, then lists the honesty-envelope components in a compact sequence, then adds the crucial historical-not-predictive qualifier. No sentence is wasted, though the length is on the high side; a slightly tighter grouping of output components would make it ideal.

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

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

With no output schema present, the description carries the burden of explaining what the tool returns, and it does so thoroughly: the probability estimate, confidence interval, sample-size guards, stability split, yearly counts, value distribution, disclaimer, and a clear caveat about historical frequency. Together with the schema's fully documented parameters, an agent has enough information to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including the detailed context-parameter instructions. The description adds only light semantic help by mentioning that preset ids come from edge_presets and symbols from edge_symbols, which the schema also already states. This matches the baseline 3 for fully schema-documented parameters.

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

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

The description names a specific verb-resource pair ('precomputed session-statistics result') and defines the exact semantic content: P(outcome | conditions) for a preset on a hosted symbol. It also distinguishes the tool from siblings by tying it to edge_presets and edge_symbols, making it clear this is the report lookup tool rather than a journal, library, propfirm, or tracker tool.

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

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

The description clearly situates the tool as a historical-frequency source and explicitly warns 'not predictions,' which helps an agent avoid misusing it for forecasting. It also tells the agent where to get required inputs ('Preset ids come from edge_presets; symbols from edge_symbols'). However, it does not explicitly state when to prefer this tool over sibling analytics tools, such as trackers_query or propfirms_simulate, so it stops short of a full when/when-not guide.

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

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

Annotations already mark this as read-only and open-world, so the safety profile is covered. The description adds useful behavioral context by clarifying that hosted data includes coverage metadata but that session statistics come from the open-source edge-stats engine over free market data, reducing the risk of expecting outcomes this tool 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?

Three sentences each add distinct value: contents, data source/semantics, and usage pipeline. The description is front-loaded with the scope and contains 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 tool with a single generic context parameter and no output schema, the description gives enough coverage detail and pipeline context for an agent to decide to call it. It does not describe the return format, but that omission is minor here because the tool's role is clearly a starting overview and the annotations cover safety.

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

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

The only parameter, context, is fully described in the schema with a 15–25 word analytics requirement, so the description is not required to add parameter detail. It adds no extra parameter semantics, but the schema already carries the full burden, so 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 description states the tool's resource precisely—what the hosted Edge Stats store covers—and enumerates concrete contents: symbols, session calendars, coverage windows, session counts, and nightly build timing. It also distinguishes itself from the sibling tools by naming edge_presets and edge_report and positioning this as the starting point.

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 guidance: 'Start here, then edge_presets for the questions you can ask, then edge_report for a result.' This tells the agent exactly when to select this tool relative to its closest siblings, with a clear sequencing.

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

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

Adds substantial behavior beyond the annotations: trade-derivation semantics (round trips, scale-ins, lone fills opening positions), ISO 8601 offset requirement, per-fill fee semantics, duplicate-skip behavior that concretely enriches the idempotentHint=true annotation, the return shape (insert counts, trades, keys), and OAuth sign-in requirement. The write semantics are consistent with readOnlyHint=false and add no contradiction.

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

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

The description is long (~5 sentences) but every clause earns its place: scope restriction, derivation rules, time format, dedupe behavior, return value, exclusions, and auth. It is front-loaded with the core purpose. It could be marginally leaner (e.g., the derivation rules could partly live in the fills schema), but for a tool with genuinely complex trade-formation semantics, the density is justified.

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?

Complete for this tool's complexity. There is no output schema, and the description correctly shoulders that burden by explaining the return value (insert counts, resulting trades, keys). All required parameters are covered by the schema, and the description supplies the non-obvious semantics — how fills map to trades, account-type restrictions, dedupe, and auth — that 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 coverage is 100%, so the baseline is 3. The description adds genuine value by explaining how fills relate to each other to form trades — critical for populating the fills array correctly — plus per-fill fee semantics and duplicate behavior. The schema already documents ISO 8601 and fee defaults, so the description supplements rather than carries the parameter meaning alone.

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 to a manual or import journal account.' It goes further by naming the account-type scope (never broker-synced) and explicitly ties to siblings — journal_update_trade for follow-up edits and journal_list_accounts as the accountId source. An agent can distinguish this tool from its journal siblings 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?

Provides explicit when-to-use (manual/import journal accounts) and when-not-to-use ('never a broker-synced one — the sync owns those') guidance. It also states what this tool does not do ('Correcting or removing an existing fill is done in the app, not here') and points to the successor action via 'with key's for journal_update_trade.' Little 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 only mark it read-only and open-world. The description adds useful behavioral context beyond those: it operates on closed trades, excludes breakevens from win rate, defaults to all time for sample-size reasons, and requires signing in with a LuxAlgo OAuth account. These are not inferred from schema or 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?

Three sentences front-load the core output and metric list, then move to selection guidance, the alternative tool, and the auth requirement. Every sentence earns its place with no filler or restating 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 analytics tool with no output schema, the description covers grouping dimensions, returned metrics, default and narrowed time windows, account scope, the closest sibling, and authentication needs. An agent can decide when to call it and what response shape to expect.

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 each parameter already documented including precedence and override behavior, so the baseline is 3. The description reinforces the default all-time window and narrowing via range/from/to, but it doesn't add meaningfully new parameter semantics beyond what the schema already 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 exactly what the tool reports: closed trades in a window grouped nine ways, with a full list of metrics including net P&L and win rate. It also names journal_overview as the sibling holding headline numbers, which lets an agent distinguish the two without inspecting 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 explicitly says this is the tool for 'what am I good or bad at' questions and routes headline-number questions to journal_overview. It also explains when the default all-time window makes sense and how to narrow with range/from/to, giving clear decision 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?

The description adds meaningful behavioral detail beyond the read-only annotation: null cells for days with no trades, days expressed in the journal timezone, and the requirement of LuxAlgo OAuth sign-in. These details inform the agent about data shape and prerequisites without contradicting 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?

The description is dense but every clause earns its place: output structure, null behavior, timezone, default month behavior, drill-down alternative, and auth requirement. It is front-loaded with the core resource and then fills in supporting details without redundancy.

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

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

There is no output schema, so the description carries the burden of explaining the return value, and it does so thoroughly: day cells, weekly totals, monthly totals, and null semantics. Combined with read-only annotations and schema-documented parameters, nothing essential is missing for an agent to call this tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents `month`, `context`, and `accounts` thoroughly. The description adds one useful default hint ('Omit `month` for the current month') but does not need to compensate for missing parameter documentation, so the baseline score of 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?

The description states exactly what the tool returns: one month of the P&L calendar with week rows, day cells, and monthly aggregates. It differentiates itself from journal_get_day by explicitly framing that tool as the day-level drill-down, so an agent can pick the right sibling 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?

The description gives concrete usage guidance: omit `month` for the current month and use journal_get_day to drill into a single day. It does not enumerate all alternative siblings such as journal_overview or journal_breakdown, but the context for when this calendar view is appropriate is clear.

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

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

Discloses null stats when no trades, which subset of trades is returned, and that notes include ids. Notes OAuth requirement. readOnlyHint and openWorldHint are consistent and the description adds useful null/edge-case behavior beyond annotations.

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

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

A dense, front-loaded definition that packs return contents, trade semantics, timezone, use cases, and auth requirement into three sentences without redundancy.

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

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

With no output schema, the description compensates by enumerating what the response contains, including the null-stats edge case and trade classification. It does not describe behavior for nonexistent days, but this is a minor gap given the detail provided.

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 already provides 100% parameter documentation. Description adds the journal-timezone clarification for date but does not discuss the optional accounts parameter, so it adds only marginal value 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?

Description clearly states it retrieves a single journal day with specific contents (stats, trades, notes). It distinguishes itself from broader journal tools by scoping to one day and explicitly names a related sibling (journal_update_note).

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 use cases ('how did Tuesday go', finding note ids for journal_update_note). It does not enumerate exclusions versus siblings like journal_list_trades, but the single-day scope and named workflow make usage clear.

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

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

Annotations already establish readOnlyHint=true, but the description adds valuable behavioral context: it requires authentication (OAuth), which is not captured in annotations. It also spells out the runtime data so the agent knows exactly what fields to expect, including effective values, corrections, hidden flags, per-exit P&L, and annotation types. The only minor gap is lacking explicit note about pagination or absence of side effects, but overall it exceeds the annotation baseline.

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

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

The description is a bit long but each sentence serves a distinct function: the first defines the output, the second gives the invocation context, and the third covers auth. The information is front-loaded with the core payload, and the style is grammatically dense without being tautological. It could be slightly shortened without losing value, but the structure is logical and weaves all necessary cues together.

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

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

Given there is no output schema, the description carries the burden of explaining the return payload, which it does thoroughly (fields listed, fills with effective values, hidden flags, P&L, annotations). It also covers the prerequisites (OAuth) and the environment in which the tool should be selected (after list tools, before annotating). There is nothing an agent would need to know that is absent for safe invocation.

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

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

The input schema already documents both parameters at 100% coverage (according to context signals). The description adds meaningful instructions for the 'key' parameter: "Never construct one" and tells exactly where to obtain it (journal_list_trades, journal_get_day, journal_search_notes, journal_add_trade). This is a practical guardrail beyond the schema. The context parameter's purpose is described but the description doesn't need to repeat schema content; the added guardrail earns a score above the baseline 3.

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

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

The description clearly states the resource and action: "One trade in full" with a specific verb (get) and the resource (a single journal trade). It enumerates what is included (summary fields, fills, P&L, annotations), distinguishing it from list-level tools like journal_list_trades and journal_get_day. No ambiguity about what this tool returns.

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

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

The description explicitly states when to use this tool: "After journal_list_trades or journal_get_day when the user asks about a specific trade or before annotating it." This provides a clear contextual trigger and a concrete alternative-avoidance guide. It also mentions the prerequisite of a LuxAlgo account (OAuth), which is an additional usage condition.

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

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

Annotations already mark this as read-only; the description adds an explicit OAuth sign-in requirement and the empty-list semantic. It also defines the special kind values (sync/import/manual) and states the returned timeZone. No contradiction with readOnlyHint/openWorldHint.

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

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

The description is ~90 words and front-loads the main purpose before usage guidance, empty-list behavior, and auth. The first sentence is long but packs necessary field and enum context with no filler. Could be broken up for readability, but nothing is wasted.

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

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

With no output schema, the description lists all returned account fields plus timeZone, and explains the journal terminology. It covers prerequisites (call first, OAuth sign-in), empty-results meaning, and relationship to other journal tools. An agent has everything needed to invoke and interpret the result.

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

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

The only parameter, 'context', has a full schema description covering its usage, so the baseline is 3; the tool description does not add further parameter-level detail. It focuses on output fields rather than input semantics, which is acceptable given 100% schema coverage.

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

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

States a specific verb and resource: lists the signed-in user's trade-journal accounts and enumerates the returned fields. It also distinguishes itself from journal siblings by explaining that these ids feed every other journal tool's accounts filter, and clarifies account 'kind' values. No ambiguity about what it does.

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 directs the agent to call this first, and explains why: every other journal tool's accounts filter takes these ids and rejects unknown ones, and journal_add_trade requires a manual or import account. It also notes empty list means no journal yet, guiding next steps. No alternative tool is named, but the dependency chain is made clear.

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

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

The description adds meaningful behavioral context beyond the readOnlyHint and openWorldHint annotations: it returns items ordered 'most-used first' with counts, covers both open and closed trades, and discloses the OAuth requirement for signing in with a LuxAlgo account. This gives the agent operational expectations that annotations alone do not convey.

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

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

The description is four sentences with no filler. It front-loads the core purpose, then provides the key usage guidance, an exclusion, and the authentication requirement. Every sentence contributes 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?

Given no output schema, the description still conveys the essential return semantics: the list includes every tag, mistake, and playbook id, sorted most-used first, with the number of trades carrying each. Combined with the rich schema and annotations, an agent has enough information to call the tool correctly and interpret its results.

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

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

Schema description coverage is 100%, so the schema already documents the 'context' and 'accounts' parameters thoroughly. The tool description does not add parameter-level detail, but it does not need to because the schema carries the full semantic load.

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

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

The description clearly identifies the resource ('tags, mistakes and playbook ids') and the action ('list'), and defines the exact scope: the user's annotation vocabulary across all open or closed trades. It also distinguishes itself from trade summaries by stating per-trade tags are not included here, which helps an agent separate it from sibling tools like journal_get_trade.

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

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

The description explicitly tells the agent when to use this tool: 'Check it before journal_update_trade so new annotations reuse the user's own words instead of minting near-duplicates.' It also states what is not covered here ('Per-trade tags are on each trade summary, not here'), giving the agent clear routing guidance versus alternatives.

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

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

Despite readOnlyHint annotation, the description adds valuable behavioral context: default sort/order, handling of missing sort values, pagination via cursor, and requirement of OAuth sign-in. It also discloses that open trades are always listed, which is not in annotations.

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

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

The description is dense but well-structured, front-loading the purpose, then covering filtering, sorting, pagination, and examples in a logical flow. Every sentence adds necessary detail without fluff.

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

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

Given the tool's complexity (12 parameters), the description covers all key aspects: return fields, sorting nuances, filtering, pagination, examples, and explicit contrast with journal_get_trade. No critical missing information.

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 83% coverage, the description reinforces parameter semantics by clarifying default sort values, the field names used in sorting, and how filters combine. It explains ambiguous aspects like 'from/to' day window applied to open day and that netPnl is after fees.

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

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

The description clearly states it lists journal trade summaries with enumerated fields, default ordering, and explicit mention of what is not included (fills, note text). It differentiates from journal_get_trade by noting that the latter has full details.

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 guidance on when to use this tool (listing trades) versus journal_get_trade for full trade details. Includes filtering, sorting, pagination instructions, and example use cases with specific parameter combinations.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context beyond that: closed trades bucket by close day in the journal timezone, open positions count toward any window that reaches today, null metrics are not computable yet (e.g. profitFactorIsInfinite), and compare adds a 'previous' equal-length window. It also discloses the OAuth sign-in requirement. This is strong added context, though it doesn't detail the exact response shape (no output schema exists), so 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?

The description is dense but well-organized: it front-loads the core purpose and metric list, then covers windowing, compare, nulls, sibling routing, and auth in a logical order. Every sentence adds information. It is slightly long, but the tool is genuinely complex (many metric groups, multiple windowing modes, sibling tools), so the length is justified. A 5 would require even tighter grouping of the metric enumeration.

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 read-only dashboard tool with no output schema, the description covers the key things an agent needs: what metrics come back, how windows work, how compare behaves, how nulls are represented, which siblings to use for other questions, and the auth requirement. It does not describe the response structure or pagination, but the metric list is detailed enough to set expectations. The openWorldHint annotation also signals that results may vary, which the description supports with the null-metric note. A 5 would need explicit return-shape or error details.

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 six parameters. The description adds value beyond the schema by explaining the default window (last 30 days), the semantics of compare ('adds previous — the equal-length window just before'), and the timezone bucketing behavior that affects from/to interpretation. It also clarifies that accounts can be omitted for every account. This exceeds the baseline 3 for full schema coverage.

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

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

The description opens with a specific verb and resource ('journal dashboard in one call for a window') and enumerates the exact metric groups returned (performance metrics, Edge Score components, per-day P&L, equity curve, open positions, accounts/settings). It also distinguishes itself from siblings by naming journal_breakdown and journal_list_trades as the tools for different questions. This is a clear, specific definition that an agent can act on.

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

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

The description explicitly states when to use this tool versus alternatives: 'Use journal_breakdown for where the P&L comes from and journal_list_trades for the trades themselves.' It also gives concrete usage context: defaults to last 30 days, how to request 'all' or explicit from/to, and the compare behavior. This is explicit routing guidance, not just implied context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond the annotations: the stream is 'newest first as one stream split by kind', keyset pagination via cursor/nextCursor, case-insensitive filtering, and the OAuth sign-in requirement. It does not describe the exact response shape, but with no output schema and read-only semantics, the disclosed behavior is sufficient.

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

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

The description is a single dense paragraph that front-loads the core purpose, then packs filters, pagination, and auth into a compact sequence. Every sentence earns its place; there is no filler or repetition of schema details.

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 8 parameters and no output schema, the description covers the essential call semantics: result kinds, filter behavior, pagination, and auth. The only minor gap is that it doesn't describe the exact response envelope (e.g., whether results are wrapped in a data object), but the keyset-pagination mention and the read-only annotations make the tool safely callable without that 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 88%, so the schema already documents most parameters. The description adds meaning beyond the schema by explaining the relationship between `symbol` and the two note kinds (day notes have no symbol and drop out), and by clarifying that `accounts` can be omitted for every account. It also explains the `cursor`/`nextCursor` keyset-pagination pattern, which is not fully captured in the schema.

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

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

The description opens with a specific verb and resource ('Search the notes feed'), then immediately distinguishes the two result kinds (`notes` vs `tradeNotes`) and names the sibling tools used to update each. This clearly differentiates it from journal_get_day, journal_get_trade, and journal_list_trades, which are the closest siblings.

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

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

The description explicitly states when to use this tool ('Search the notes feed'), what filters are available, and that omitting every filter returns the latest notes. It also names the sibling tools for updating the two note kinds (journal_update_note, journal_update_trade), giving an agent clear routing guidance. The symbol filter caveat ('day notes have no symbol and drop out') is a precise usage condition.

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

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

The description adds significant behavioral context beyond annotations: it explains the whole-body replacement semantics ('to append, read the current text first'), the required OAuth authentication, and the return of the updated note. It complements the annotations (readOnlyHint=false, idempotentHint=true) without contradiction, giving the agent essential execution details.

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

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

Three concise sentences, each earning its place: purpose and note id source, behavioral replacement note, and routing/alternative plus auth and return. Front-loaded with the core action, no redundancy, and perfectly structured for quick comprehension.

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

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

The description is complete for an agent to call this tool correctly: it covers the action, the source of the identifier, the replacement semantics to avoid data loss, the alternative tool, the authentication requirement, and the return value. With full schema coverage and this description, an agent has all necessary information.

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

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

The schema already covers all parameters with 100% description coverage, so the baseline is 3. The description adds value by clarifying that 'body' is the full new text (reinforcing the replacement behavior), and that 'date' is for moving the note (matching the schema). It also notes the source of noteId, which is not in the schema. This slightly elevates it above baseline.

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

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

The description clearly states the tool replaces a day note's text and/or moves it to another day, using the note's id. It distinguishes itself from journal_update_trade by explicitly naming the alternative for trade notes, making its purpose unambiguous and easily differentiable from siblings.

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

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

The description explicitly specifies when to use this tool (updating existing day notes) and when not to (trade notes via journal_update_trade). It also indicates the source of the note id (from journal_get_day or journal_search_notes), providing clear selection and exclusion criteria.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=true, so the mutation and idempotency profile is covered. The description adds valuable context beyond that: whole-list replacement semantics, null-to-clear behavior, the fact that stopLoss is what realized R is measured against, and the OAuth sign-in requirement. It does not contradict the annotations. A small gap is that it doesn't discuss partial-update semantics for fields not mentioned, but the field list and null behavior largely cover it.

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

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

The description is a single dense paragraph that front-loads the core purpose, then packs the most decision-relevant semantics (replacement vs. additive, null-clearing, what is not touched, return value, auth) into a compact space. Every sentence earns its place; there is no filler or repetition of schema content.

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

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

For a 14-parameter mutation tool with no output schema, the description covers the key behavioral rules an agent needs: which fields are user-owned, how list replacement works, how to avoid clobbering, null semantics, return value, and auth. It doesn't spell out every parameter's meaning, but the schema covers those at 86%. The main gap is that it doesn't describe error conditions or what happens with invalid keys, but the description is otherwise complete enough for correct invocation.

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

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

Schema description coverage is 86%, so the schema already documents most parameters. The description adds meaning beyond the schema by explaining the replacement-vs-add/remove distinction, the null-clears convention, and the relationship between stopLoss and realized R. It also points to journal_list_tags for valid tag vocabulary. This is meaningful added value over the schema, though a few parameters (e.g., reviewed, playbookId) are only lightly elaborated in the description.

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

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

The description opens with a specific verb and resource ('Annotate a trade') and immediately scopes it to 'user-owned fields only', which distinguishes it from any trade-mutating sibling. It enumerates the exact fields, so an agent knows precisely what this tool does and what it deliberately does not do (fills, prices, P&L).

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

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

The description gives explicit when-to-use guidance: use addTags/removeTags/addMistakes/removeMistakes instead of the whole-list replacement fields when changing a few entries, and check journal_list_tags for existing words. It also states the tool does not touch fills/prices/P&L, which tells the agent not to reach for it for those concerns. This is strong routing guidance relative to siblings.

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

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

The description goes beyond annotations by disclosing that the operation never overwrites because days can hold multiple notes, that it returns the note with its id, and that OAuth sign-in with a LuxAlgo account is required. These are non-obvious behavioral traits that help an agent set expectations, and nothing contradicts 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?

Three sentences with each earning its place: the core action and scope, the distinction from alternatives, and the return/auth information. Front-loaded and free of filler.

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

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

For a write tool with three parameters and no output schema, the description covers the key contextual facts: non-destructive append behavior, return value, auth requirement, and clear sibling routing. The schema handles parameter details, 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 description need not repeat parameter details; it only reinforces the date format/timezone, which is already in the schema. It does not add meaning for body or context beyond what the schema provides, so the baseline of 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?

The description states a specific verb and resource ('Add a new note to a trading day') and immediately distinguishes scope: any day, traded or not, and never overwrites. It explicitly separates itself from journal_update_note and journal_update_trade's notes, making the tool's purpose unambiguous among siblings.

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

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

It gives explicit when-to-use ('any day, traded or not') and when-not-to-use: 'to change an existing note use journal_update_note, and for a note about one specific trade use journal_update_trade's notes'. This directly routes the agent to the correct alternative based on the task.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a safe read operation. The description adds useful context about the return format (markdown write-up with definition, formula, trader interpretation, indicator implementations) and the requirement for an exact slug. However, it doesn't disclose behavior like error cases for invalid slugs or whether the markdown is rendered or raw, but the annotations cover the safety profile, 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?

Three sentences with zero waste. The main purpose is front-loaded, the usage condition is stated clearly, and the prerequisite/routing is at the end. Every sentence earns its place.

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

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

Complete for a read-only retrieval tool with 100% schema coverage and annotations covering the safety profile. The description explains what the tool returns, when to use it, and how to get the required slug. The only minor gap is not describing error behavior for invalid slugs, but that's not essential for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters. The description adds context for the slug parameter by explaining it must be the exact slug and pointing to search/list tools, which is helpful. The context parameter is fully documented in the schema with detailed instructions, so the description doesn't need to add more. Baseline 3 is correct 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 a specific verb ('Explain'), a specific resource ('a trading concept'), and the exact content of the write-up (definition, formula, how traders read it, indicator implementations). It also distinguishes itself from sibling tools by noting it returns the full markdown write-up, which is distinct from library_get_family, library_get_indicator, 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?

The description explicitly says when to use it: 'Use for any "what is X / how does X work" question.' It also gives a clear prerequisite and routing instruction: 'Needs the exact slug — find it with library_search or library_list_concepts.' This tells the agent exactly when to call this tool versus its siblings.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so no safety disclosure is needed. The description adds useful behavioral detail beyond the schema: the output is markdown, contains a written overview, and includes a complete concept roster, which helps the agent set expectations for the returned content.

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

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

The description is a single tight sentence with an em-dash clarification and a short usage clause. Every part earns its place: what the tool returns, in what format, and when to use it.

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

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

For a read-only retrieval tool with two well-documented parameters and no output schema, the description fully covers the purpose, the content of the result, and the invocation context. An agent has enough information to select and call this tool correctly.

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

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

Schema description coverage is 100%, and the schema already documents both 'key' and 'context' clearly, including an enum for 'key'. The description reinforces the concept with examples like 'smc-ict' and 'Wyckoff' but does not add substantial meaning beyond the schema, 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 a specific verb and resource: retrieving a family's hub page as markdown, including the written overview and complete concept roster. It also gives concrete examples ('SMC', 'Wyckoff'), making it distinguishable from sibling tools like library_get_concept and library_list_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?

It explicitly says to use this after library_list_families or when the user asks about a whole area like 'SMC' or 'Wyckoff'. It does not explicitly state when not to use it or name an alternative like library_get_concept, so it stops short of 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 provide readOnlyHint=true and openWorldHint=true, covering the safety model. The description adds output-content details but no additional behavioral traits such as side effects, prerequisites, or rate limits, which is adequate given the read-only annotation.

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 with zero waste: the first lists the contained details and routes code requests to a sibling, the second states the usage trigger. Purpose and routing are front-loaded.

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

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

For a single-item getter with a fully documented schema, the description covers what is returned, when to use it, and how to obtain source code. It does not point to list/search siblings, but that gap is minor for this tool's role.

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%: both slug and context have descriptions, with slug given an example. The tool description reinforces that slug identifies a specific indicator but does not add meaning beyond the schema for either parameter; 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?

Description states a specific verb+resource: 'Details for one indicator' and enumerates the contained fields. It distinguishes from library_get_source_code by explicitly routing code-fetching to that sibling, making the tool's scope unmistakable.

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

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

Explicitly gives a usage condition: 'Use when the user asks about a specific indicator' and points to library_get_source_code for code retrieval. It does not mention alternatives like library_get_concept or library_list_indicators, so it lacks full exclusions but provides clear context.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, covering the safety profile. The description adds that sources are long and that the tool returns the full working code, but it does not disclose additional behavioral details such as output size limits or formatting. This is adequate but not rich.

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

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

The description is two sentences, front-loads what the tool returns, and then gives essential routing guidance. Every sentence earns its place and there is no redundancy.

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

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

This is a simple read-only retrieval tool with two well-documented parameters and no output schema. The description explains what is returned, when to use it, and why it is separate from a sibling, which is sufficient for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the slug and context parameters are already documented. The description does not add any meaning beyond the schema, which is the baseline case where the schema carries the burden.

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

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

The title and description clearly state this tool returns the full, working source code of a Library indicator. It explicitly distinguishes itself from library_get_indicator by noting the source is kept separate because it is long, so an agent can tell exactly what this tool is for.

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

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

The description gives explicit when-to-use guidance: 'call it only when the user wants the code itself.' It also names the alternative library_get_indicator and explains the separation, making the decision between siblings 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 and openWorldHint=true, so the description does not need to repeat safety. It adds useful behavior: pagination and optional family filtering. No contradiction with annotations.

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

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

Two sentences with zero waste; the core purpose is front-loaded and the usage guidance is compact and direct.

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 paginated list tool with an optional family filter, the description covers the purpose, usage, and pagination. Without an output schema, it does not describe the return format, but that is not critical for a browse/enumerate 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 75%, with descriptions for context, page, and page_size, and an enum for family. The description adds 'optionally one family' which clarifies family usage but does not meaningfully supplement the schema's parameter details.

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

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

The description clearly states the verb 'browse' and the resource 'every trading and technical-analysis concept in the Library,' and it explicitly differentiates from siblings like library_search and library_get_concept by mentioning their purposes.

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

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

It explicitly states when to use the tool ('enumerate a topic area or find slugs for library_get_concept') and when not to ('for keyword lookup prefer library_search'), naming the alternative tool directly.

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, covering safety. The description adds useful behavioral context by specifying what is returned (17 families, counts, hub links) and the tool's top-level scope. It does not mention ordering, pagination, or exact response structure, so it adds moderate but not rich behavioral detail.

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

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

Two sentences with no filler. The core identity ('top-level taxonomy'), contents (17 families, counts, hub links), and usage context ('natural first call') are all front-loaded and every phrase earns its place.

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

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

For a simple read-only list tool with one well-documented parameter, the description gives enough to understand what the tool returns and when to call it. The absence of an output schema is mitigated by the concrete enumeration of returned elements; no critical information is missing for a first-orientation call.

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

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

Schema description coverage is 100% for the single context parameter, and the schema provides a thorough explanation of that parameter. The description does not need to repeat it; a baseline 3 is appropriate since the description adds no extra parameter-level meaning.

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

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

The description clearly states the resource (Library's top-level taxonomy), the operation (list families), and concrete contents (17 families with concept counts and hub links). It stops short of explicitly differentiating from siblings like library_list_concepts or library_get_family, though 'top-level taxonomy' and 'natural first call' imply its distinct role.

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

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

The phrase 'natural first call for orientation' gives a clear when-to-use signal, positioning it before more specific library tools. It does not name alternatives or exclusions, but the orientation guidance is sufficient for a simple read-only listing tool.

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

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

Annotations already indicate readOnlyHint and openWorldHint, and the description adds useful behavioral context: server-side sorting, newest-first default, AND-combined tag filtering, and the set of supported filter dimensions. It does not mention pagination behavior, but the schema already documents page and page_size defaults.

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 well-structured sentences: the first states the core behavior, the second enumerates filter dimensions, and the third gives usage examples and the sibling alternative. No wasted words; all content is decision-relevant.

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 11-parameter browsing tool, the description effectively covers the primary filtering dimensions, ordering behavior, and the main alternative. It omits a few available parameters like text, direction, and pagination, but those are well-documented in the schema and the description provides enough context for correct invocation.

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

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

Schema description coverage is high (82%), so the schema carries most parameter meaning. The description echoes family, concept, tags, platform, and tier filters, and adds the 'AND-combined' tag semantics, though those are largely already present in the schema. It adds modest semantic value but not significant new parameter detail.

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

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

The description uses a specific verb ('Browse') with a clear resource ('indicator catalog') and immediately distinguishes this tool from the sibling library_search. It conveys a listing/filtering purpose that is distinct from search, concepts, families, and tags tools.

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

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

It explicitly states when to use the tool ('structured browsing') with concrete examples like 'latest indicators' and 'everything in the volatility family', and names the alternative ('library_search') for keyword discovery. This gives an agent clear routing guidance.

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

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

The readOnlyHint annotation already covers safety, and the description adds useful behavior not in annotations: the tool returns ids intended for filtering and clarifies the relationship to the concept-family taxonomy. For a simple read-only list, this is sufficient 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?

Two tight sentences with no filler. The first names the resource and examples, and the second gives the downstream use and taxonomy relationship.

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 low-complexity read-only list with one generic parameter, the description covers what is returned (ids), how to use them (tags filter of library_list_indicators), and how tags relate to the taxonomy. No output schema exists, but the return semantics are sufficiently stated.

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

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

The only parameter is context, which is fully documented in the schema with a generic analytics instruction. The tool description adds no domain-specific parameter semantics, but with 100% schema coverage 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?

The description clearly identifies the resource as 'The Library's indicator tag vocabulary', gives concrete examples of tags, and states the output is ids for the tags filter of library_list_indicators. It also distinguishes itself from concept/family taxonomy tools.

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

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

It explicitly connects the tool to its downstream use: obtaining tag ids to pass as the tags filter of library_list_indicators. It also notes that tags are orthogonal to the concept-family taxonomy, helping avoid confusion with library_list_concepts or library_list_families. It stops short of explicit when-not-to-use language.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavioral context: alias-aware matching, the fact that results carry slugs and canonical URLs, and the scope of the search (800+ concepts and indicators). It doesn't describe pagination or result ordering, but for a search tool with readOnlyHint, the added context is sufficient to push above baseline.

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

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

The description is two sentences with zero filler. The first sentence front-loads the core purpose and scope, and the second sentence adds the usage directive and output value. Every clause earns its place: 'alias-aware,' '800+,' 'slugs for the get tools,' and 'canonical URLs for citation' all convey distinct, useful 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 search tool with readOnlyHint and openWorldHint annotations, the description covers the essential decision points: what it searches, when to use it, and what the results contain. It doesn't describe result format or ordering, but no output schema exists and the description's mention of slugs and URLs gives an agent enough to know what to expect. The only minor gap is not stating that results are paginated or how to control it, but the limit parameter in the schema covers that.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds the alias-aware behavior and the 'start here' guidance, which enriches the query parameter's meaning, but it doesn't add detail about type, limit, or family beyond what the schema provides. Baseline 3 is appropriate because 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 a specific verb ('Search'), a specific resource ('the LuxAlgo Library'), and the scope ('800+ concepts' and '800+ ready-to-use indicators'). It also distinguishes itself from sibling get/list tools by saying 'results carry slugs for the get tools plus canonical URLs for citation,' which tells an agent this is the entry point for discovery rather than retrieval. The alias-aware note ('stochastics' finds Stochastic Oscillator) further clarifies the tool's unique value.

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

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

The description explicitly says 'Start here whenever you have a name, informal term, or topic,' which is a clear when-to-use directive. It also implies the alternative: once you have slugs, use the get tools (library_get_concept, library_get_indicator, etc.). This is strong routing guidance that helps an agent choose between library_search and the many sibling library 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 and openWorldHint, so the safety profile is covered. The description adds meaningful behavioral context beyond that: it requires signing in with a LuxAlgo account via OAuth, which is important for an agent to communicate or handle correctly. No contradiction with annotations.

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

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

Three sentences with no filler: it states what the tool returns, when to use it, and the auth prerequisite. The most important information is front-loaded, and every sentence earns its place.

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

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

For a simple read-only account-info tool, the description provides the resource scope, example data categories, use cases, and auth requirement. There is no output schema, but the description's list of plan tier, entitlements, and profile basics gives a reasonable sense of what to expect. It could mention return format, but that is not critical for this tool.

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

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

Schema description coverage is 100%, and the only parameter, context, has a detailed description in the schema. The tool description does not add parameter-level meaning beyond the schema, so the baseline score of 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?

The description clearly identifies the resource (the signed-in user's LuxAlgo account) and lists its contents: plan tier, entitlements, and profile basics. It also states concrete use cases, though it reads more as a noun-phrase description than a verb-led action, and it does not explicitly contrast with the sibling tools (which are mostly unrelated data or library tools).

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

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

It explicitly says to use this tool to tailor answers to plan limits or when the user asks what plan they are on. This gives clear context for when to invoke it, although it does not discuss exclusions or alternatives—likely unnecessary given the sibling set.

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 and openWorldHint, and the description adds substantial non-redundant context: live data source (LuxAlgo public keyless API with env-var origin override), inference behavior with `inferredFields` disclosure, refusal of challenges whose loss rules cannot be established, the simulated-vs-declared distinction (flagsNotSimulated), and the caveat that each firm's page is authoritative. It even discloses a non-obvious behavioral trait: 'one outsized day effectively raises the target until the best-day share complies'. No contradiction with annotations.

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

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

The description is very long (roughly 450 words) but every block earns its place: rule semantics, drawdown modes, units, provenance, and sibling routing are all consequential for correct use. The main purpose is front-loaded in the first sentence. It is dense rather than padded, though it approaches the upper bound of reasonable length; slightly tighter phrasing on the drawdown-mode enumeration would improve it.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so exhaustively: it enumerates every rule category in the ChallengeSpec, explains unit conventions (percent vs fraction, with winRate called out as the exception), describes provenance/inferredFields, covers refusal behavior, and clarifies how results feed downstream simulation tools. Given the tool's genuine complexity and zero output-schema support, 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 the baseline is 3. The description adds no parameter-specific semantics beyond the schema; firmId and challengeId are already documented in the schema as originating from propfirms_list_simulatable. The extensive units guidance applies to return values rather than parameters, so the description does not need to compensate for any schema gap.

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

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

The description opens with a specific verb+resource: 'Fetch one directory challenge's complete ruleset (ChallengeSpec)'. It clearly scopes the tool to a single challenge's simulatable encoding and explicitly differentiates from siblings in the final sentence: 'the directory listing with every captured field, plus live offers, is propfirms_get and propfirms_search_challenges'. An agent can distinguish this from the sibling prop-firm tools without opening any schema.

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

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

The description gives an explicit use case: the returned `challenge` object is exactly the shape simulation tools accept as inline `spec`, so an agent can copy, modify, and re-simulate. It names alternatives and their scope (propfirms_get and propfirms_search_challenges for listings/offers), states prerequisites (ids come from propfirms_list_simulatable), and even specifies the refusal behavior for unsimulatable challenges. When-to-use and when-not-to-use are both explicit.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description adds substantial behavioral context: results are ordered by EV for specific inputs and are not endorsements, determinism depends on seed, flagsNotSimulated can make numbers optimistic, consistency and payout gating are simulated, and results are distributions under assumptions. It also instructs how to present results, which is unusually useful.

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

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

The description is long but well-structured with labeled sections (UNITS, DETERMINISM, ASSUMPTIONS) and front-loads the core purpose in the first sentence. There is mild redundancy around 'not a ranking' and repeated emphasis on assumptions, but each section carries meaningful operational guidance.

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

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

There is no output schema, but the description enumerates the returned row fields (perAttemptPassProbability, fundedProbability, expectedAttempts, expectedCost, evTotal, pEvPositive, daysToFundedP50, flagsNotSimulated) and explains how to interpret them. Combined with the caveats about assumptions and determinism, an agent has enough to invoke the tool and present results 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. The description adds valuable cross-cutting semantics beyond the schema: unit conventions (percent units vs. winRate as a fraction), the role of seed in reproducibility, the meaning of flagsNotSimulated, and the importance of reporting assumptions alongside numbers. Most parameter-level detail is already in the schema, but the description enriches interpretation.

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

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

The description opens with a specific verb and resource: 'Simulate the SAME trader across several challenges ... and return one row per challenge sorted by expected value.' It also clearly distinguishes this from a ranking and from propfirms_simulate, so an agent can tell it apart from sibling tools.

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

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

The description gives clear context: use this when comparing multiple challenges under identical trader inputs, and it explicitly routes to propfirms_simulate for full per-challenge distributions ('For full per-challenge distributions run propfirms_simulate on the interesting rows'). It does not enumerate exclusions against every sibling, but the key alternative is named.

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

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

Annotations already mark the tool as readOnly and openWorld, and the description adds meaningful behavioral details beyond that: uncaptured null fields are omitted, and challenges reference applicable offers via offerIds into the firm-level offers list. This clarifies response shape and entity relationships in a way annotations cannot.

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 core purpose and content list, followed by routing and data-model notes. Every sentence contributes either invocation guidance, alternative routing, or behavioral detail; the length is justified by the dossier's complexity.

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

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

For a read-only lookup with only two fully documented parameters and no output schema, the description is complete: it names the input source, enumerates returned content, explains null omission and referencing behavior, and routes to relevant siblings. Nothing critical is missing for correct selection and invocation.

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

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

Schema coverage is 100%, with propfirmId already described as a 'Public firm slug'. The description adds useful operational guidance by reinforcing lookup-by-slug and explicitly directing the agent to propfirms_search to discover valid slugs, which goes beyond the schema's static description.

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

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

States a specific verb and resource: returns a single prop firm's 'full dossier by slug' and enumerates exactly what that dossier contains (profile, challenges, offers, written overview). It also names the sibling propfirms_search for slug lookup, so an agent can tell it apart from related search 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?

Clearly indicates when to use the tool (to retrieve a full dossier by slug) and explicitly points to alternatives: 'Find slugs with propfirms_search' and 'use propfirms_pass_rates' for pass odds. It lacks explicit exclusionary guidance such as 'do not use for challenge-only lookups', but the 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?

Beyond the readOnlyHint and openWorldHint annotations, the description discloses data provenance, live-data behavior, origin overridability, inference policy with inferredFields disclosure, refusal to guess loss rules, alphabetical non-endorsement, and that firm pages remain authoritative. This is rich behavioral context that materially changes how an agent should interpret results.

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

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

The description is long but structured into a clear first-sentence summary, usage guidance, data-source section, and differentiation note. The main redundancy is the not-simulatable policy being stated twice, but each remaining sentence carries distinct value, so the overall structure is still strong.

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 returned fields, the notSimulatable collection, and inferredFields provenance. It also explains when to call this tool versus the search siblings新材料, how data is sourced, and how to handle inference caveats. An agent has enough context to call it and interpret results 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 the schema already documents both parameters, including the productType enum and the meaning of omitting it. The description adds no additional parameter-level semantics, 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 names a specific verb and resource: it lists prop firms and their simulatable challenges from the live LuxAlgo directory, enumerating the exact fields returned. It also explicitly distinguishes itself from propfirms_search tools by stating it only lists honestly encodable firms and challenges.

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 instructs the agent to call this tool first to discover valid firmId + challengeId pairs for five sibling tools, and explicitly says the full directory is served by propfirms_search, propfirms_search_challenges, and propfirms_search_offers. It also gives clear when-not-to-use guidance by noting challenges with unestablishable loss rules are not simulated or guessed.

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, the description discloses common random numbers for smooth curves, byte-identical reproducibility with seed, cost scaling with grid size, assumption flags and disclaimer, and that results are distributions, not promises. This is substantial behavioral context an agent needs to interpret results correctly.

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

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

The description is long but tightly organized into labeled sections (UNITS, DETERMINISM, ASSUMPTIONS) and front-loaded with the core purpose and result semantics. Every sentence adds operational or interpretive value; there is no filler.

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

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

With no output schema, the description carries the burden of explaining results, and it does: it names the key output fields (bestByPassProbability, bestByEv, diverges, assumptions.flags, assumptions.disclaimer), clarifies probability units, explains reproducibility, and warns about cost. This is sufficient for an agent to call the tool and interpret the response 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 valuable cross-parameter semantics: percent units for Pct fields and percent-mode risks, winRate as a fraction, grid defaults and units by riskMode, and the explicit note that riskValue is not a parameter here. It does not enumerate all 20 parameters, but the schema already documents those.

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

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

The description states a specific operation: sweep risk-per-trade over a grid, run full journey simulations, and report two named optima (bestByPassProbability and bestByEv). It clearly distinguishes this from generic simulation or pass-rate tools by focusing on risk optimization, even without explicitly naming a sibling.

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

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

The description gives clear when-to-use context (grid optimization), explicit reporting requirements (never present one number, report both optima and trade-off), and practical iteration guidance (coarse grid first, then refine). It notes an exclusion (parametric trader only, riskValue not a parameter), though it does not explicitly name a sibling tool for single-point simulation.

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

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

The annotations already mark the tool as readOnly and openWorld, and the description adds valuable behavioral context: results are deterministic per ruleset, cached, cheap to call, computed from encoded rules, and not a ranking. It discloses the reference archetypes and risk assumptions, the provenance handling for inferred fields, and the caveat to check lastVerified. This goes 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?

The description is dense but front-loaded with the key purpose and differentiation. It includes a long enumeration of return values und caveats, but each detail supports correct interpretation and prevents misuse. Slightly long, but justified given the complexity and absence of an 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?

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: probabilities, confidence intervals, expected attempts, cost, EV, payout, blowup probability, assumption flags, and provenance. It also explains relevant caveats about reference odds, authoritative firm pages, and where to go for personal simulations and live offers. Nothing critical is missing for an agent to decide whether and how to call this tool.

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

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

Schema description coverage is 100%, so the input parameters are already well documented. The description adds meaning to the overall computation, such as archetype win rates and output dimensions, but it does not add much parameter-specific guidance beyond what the schema provides. The baseline of 3 is appropriate because the schema carries the parameter documentation burden.

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

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

States a specific purpose: computing reference challenge pass rates per archetype using the same engine and reference assumptions. Clearly distinguishes itself from propfirms_simulate and propfirms_simulate_trades by emphasizing 'reference odds' rather than personal statistics. The title and description align and identify the exact deliverable.

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 tells when to use this tool vs alternatives: use it for orientation and comparison, but use propfirms_simulate or propfirms_simulate_trades for the user's own statistics. It also directs the agent to propfirms_get and propfirms_search_offers for full profiles and live offers, and warns that a firm's page is authoritative. This is exemplary routing guidance.

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

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

Annotations carry readOnlyHint and openWorldHint, so the safety profile is covered. The description adds substantial behavioral detail beyond annotations: the conjunctive filter matching rule, that include only returns children matching the filters, that null fields are omitted, and the offerIds linkage into the firm-level offers list. These are non-obvious behaviors an agent must know.

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 main verb and resource, then logically structured: core semantics, simplest usage, sibling routing, data quirks, and scope limitation. Each sentence earns its place; the length is justified by the complexity of a 54-parameter search tool and there is no redundant filler.

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

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

Given the tool's complexityaine, no output schema, and only read-only/open-world annotations, the description covers what an agent needs: matching rules, include behavior, null-field omission, offerId referencing, and a clear warning that outcomes are out of scope. Nothing essential for selecting or invoking the tool 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 baseline is 3. The description adds value by grouping the 54 parameters into firm, challenge, and offer filter categories and by explaining the 'at least one challenge/offer matches all filters' semantics that applies across all params. It also clarifies the include parameter's behavior beyond the schema. Individual parameter meanings remain left to the schema, which is appropriate 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?

Description states a specific verb ('Search') and resource ('LuxAlgo's prop-firm catalog'), then defines the matching semantics precisely: a firm matches when at least one challenge/offer matches all filters. It explicitly distinguishes itself from propfirms_get, propfirms_pass_rates, and propfirms_simulate, so an agent can tell them apart 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?

Gives clear when-to-use guidance: 'Omit every filter to list all firms', and routes to alternatives explicitly ('for one firm's full dossier prefer propfirms_get', 'for simulated pass odds ... use propfirms_pass_rates or propfirms_simulate'). Also clarifies scope boundaries by stating this returns directory data, not outcomes.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses important behaviors: 'Uncaptured (null) rule fields are omitted from results and never match filters' and 'This returns each challenge's listed rules and terms, not outcomes.' It also explains the include offers behavior (deduplicated top-level offers list, offerIds referencing applicable offers) and notes that firm-wide offers are included, adding significant transparency about what the tool does and does not do.

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

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

The description is comprehensive yet well-structured: it front-loads the core purpose, then lists the filtering capabilities, usage patterns, behavioral nuances, and follow-up tools. Each sentence serves a distinct purpose—no filler or redundancy—and the flow from 'what' to 'how' to 'what next' is logical and efficient for an agent to parse.

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

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

Given the tool's high complexity (36 parameters, no output schema), the description is highly complete. It covers the search scope, filtering dimensions, two primary usage modes (propfirmId vs. challengeId), the include offers feature, null-field handling, and what the tool does NOT return (outcomes), while pointing to related tools for simulation and validation. An agent has everything needed to invoke it correctly without additional inference.

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/all parameters are already documented. The description adds meaning beyond the schema by explaining the behavior of propfirmId and challengeId (list one firm vs. fetch specific ones) and elaborating on the include parameter's behavior (deduplicated top-level offers list, offerIds). This extra context justifies a slight elevation above the baseline, though the schema remains the primary source of parameter detail.

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

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

The description opens with a specific verb ('Search') and resource ('funded-account challenges') plus scope ('across all visible prop firms'), and immediately clarifies the difference between listing one firm's challenges via propfirmId and fetching specific ones via challengeId. It also explicitly contrasts with related tools by saying 'to simulate a challenge found here pass its ids to propfirms_simulate or propfirms_pass_rates', distinguishing this search tool from its simulation and validation siblings.

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

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

The description gives clear, actionable usage guidance: 'Pass propfirmId to list one firm's challenges, or challengeId to fetch specific ones.' It also explains the include=['offers'] behavior and explicitly routes the agent to sibling tools for simulation or strategy screening, leaving no ambiguity about when to use this tool versus alternatives.

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

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

With readOnlyHint=true and openWorldHint=true, annotations already cover the safety profile. The description adds meaningful behavioral context: default filtering to live offers, the effect of challengeId (firm-wide offers included), and the result fields each offer carries. No contradictions with annotations.

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

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

Three sentences, each earning its place: what the tool searches, the default filter, key narrowing parameters, and the guaranteed output fields. Front-loaded with the core purpose, no filler.

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

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

Given 18 parameters and no output schema, the description covers the essential default behavior and output shape, while the fully described schema covers all parameters. It could mention pagination or filtering flags, but those are documented in the schema, so the description is sufficient for an agent.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates propfirmId and challengeId semantics already present in the schema and does not add deeper meaning for other parameters. It earns the baseline but nothing more.

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

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

The description uses a specific verb ('Search') and resource ('promotional offers across prop firms'), clearly identifying what the tool does. It does not explicitly name sibling tools or distinguish itself from propfirms_search or propfirms_search_challenges, though the resource type is unambiguous.

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

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

The description gives useful context about default behavior ('defaults to live offers only') and explains when to use the propfirmId and challengeId filters. It does not explicitly state when to use this tool over alternatives or provide exclusions, so usage guidance is implied rather than direct.

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 provide readOnlyHint and openWorldHint, and the description adds substantial context beyond them: determinism with seed, assumptions.flags and disclaimer that must be surfaced, data provenance and inference disclosure, refusal of non-simulatable challenges, and engine v1 details (consistency simulated, withdrawal model). No contradiction; far exceeds annotation baseline.

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

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

The description is very long but well-structured with clear sections (SIMULATED RULES, UNITS, DETERMINISM, ASSUMPTIONS, DATA SOURCE). Core purpose is front-loaded. While verbose, every section earns its place given the tool's complexity; a 5 would require tighter prose.

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

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

For a tool with 19 parameters, nested objects, and no output schema, the description is exceptionally complete: it details the returned SimResult fields (perAttempt, journey, funded, ev), explains assumptions flags and disclaimer, determinism, data source and provenance, and composition with other tools. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning to key parameters: winRate is a fraction not percent, riskValue uses percent units, R-multiples definitions, tradesPerDay model choices, and warns winRate is the most impactful input. It doesn't exhaustively describe all 19 but provides significant semantic context 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 ('Monte Carlo-simulate'), a resource ('a trader through a prop-firm challenge'), and explicitly distinguishes itself from propfirms_simulate_trades (raw trade series) and propfirms_list_simulatable (discovery). It clearly answers the core question set (pass probability, funded probability, attempts, cost, EV) and identifies the challenge by directory ref or inline spec.

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

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

Gives explicit when-to-use guidance: prefer simulate_trades when raw trade series exist; use directory references when network is available, inline specs offline; states exactly one form required and error if both/neither; explains how to feed stats from other tools (conversion to R-multiples). This is comprehensive alternative routing.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses material behavior: consistency rules and payout gating are truly simulated, newsFilter runs the simulation twice on the same seed, portfolio mode merges logs and attaches overlap analysis, results carry assumptions.flags/disclaimer that must be surfaced, and identical inputs plus seed reproduce byte-identical results. No contradiction with annotations exists; the description substantially extends them.

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

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

The description is long but tightly organized into labeled sections (TIMESTAMPED LOGS, NEWS WINDOWS, PORTFOLIO MODE, SIMULATED RULES, UNITS, DETERMINISM, ASSUMPTIONS), each carrying load-bearing information. The core mechanism and sibling differentiation are front-loaded in the first sentences, and the promotional 'WHY THIS BEATS WIN-RATE MATH' section earns its place by explaining when bootstrap resampling matters.

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 21-parameter tool with nested objects and no output schema, the description covers all input alternatives and their mutual exclusions, defaults (seed 42, paths 10k, blockMeanLength 5), output contracts (SimResult, structuredContent.newsComparison, portfolioOverlap, text summary with win rate/mean R), and required reporting obligations (relay calendar caveat verbatim, surface assumptions flags, include seed). No operationally relevant gap remains.

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?

Although schema coverage is 100%, the description adds meaning the schema lacks: blockMeanLength's operational interpretation (1 = i.i.d. destroys streaks, raise toward 10 for long regimes), tradesPerDay being required with rSeries but derived from timestamped logs, importRisk never applied silently, unit conventions for riskValue vs winRate, and the definition of R-multiples tied to rSeries. This cross-parameter guidance is essential for correct invocation.

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

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

The description opens with a specific verb and resource: 'Simulate a challenge by resampling the trader's OWN R-multiple trade series with a stationary block bootstrap instead of a win-rate model.' It clearly distinguishes this tool from its sibling propfirms_simulate by naming the alternative and the input type it requires (actual trades vs summary stats), so an agent can select it correctly 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?

Explicit guidance is given: 'Use propfirms_simulate when only summary stats are available; use this whenever the actual trades are.' It also states data requirements (at least 10 trades, 100+ strongly recommended), input mutual exclusions (exactly one of rSeries, rSeriesText, tradeLogText, tradeLogTexts), and when tradesPerDay is required vs derived. This fully covers selection and invocation conditions.

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

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

Annotations only say readOnly and openWorld; the description adds a wealth of behavioral detail beyond that: the honesty frame (not a ranking, excluded challenges counted, flags relayed), deterministic per-seed results, refusal of scopes >40 challenges, and that live discounts are not applied. This fully covers the safety and reproducibility profile the annotations omit.

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

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

The description is long but every sentence earns its place. It front-loads the purpose and strategy-input options, then covers the honesty frame and performance notes. It is well-paragraphed and dense; for 25 parameters it avoids redundancy and stays focused. A minor deduction for length, but not wasteful.

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

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

Given no output schema, the description details the returned fields (pass probability, CI, P(funded), expected attempts/cost, EV, P(EV>0), assumption flags, rule semantics). It also explains scoping, simulation cost, determinism, and related tools. An agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema: it explains the bar's semantics and reporting requirement, recommends preferring rSeries over winRate, and warns that winRate is easily overestimated. It also clarifies interaction effects (risk sizing moves numbers) and mentions the funded horizon scaling EV. These are meaningful additions.

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 direct answer to the user's question ('which challenges would MY strategy actually pass?') and states the resource (every simulatable challenge in the live directory) and the action (simulate and split by a bar). It explicitly names sibling tools (propfirms_optimal_risk, propfirms_search_challenges, etc.) for differentiation, making the purpose unmistakable.

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

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

It clearly frames the tool as a multi-challenge screening tool and points to propfirms_optimal_risk for a focused sweep afterwards. It also gives practical guidance like 'scopes above 40 challenges are refused' and 'narrow the scope instead.' It does not explicitly state 'when not to use this,' but the alternative and the condition are implied strongly enough.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds behavioral detail about the output (row count, freshness, live-tree vs deep-history coverage, ticker-searchability) and the detailed-view contents, which goes beyond annotations and helps set expectations.

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

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

The description is three sentences that move from catalog scope to return values to usage guidance, with no filler. The first sentence is long, but every item in the list earns its place by naming a dataset category; the actionable advice is saved for the end.

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 metadata/list tool, the description covers the dataset set, summary fields, the detailed view, and its relationship to trackers_query. With annotations supplying the read-only/open-world profile and no output schema, the description is sufficiently complete for correct invocation; minor details like pagination are not essential here.

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

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

With 100% schema description coverage, the baseline is 3, but the description adds meaning beyond the schema by explaining what the dataset parameter provides (full field roster, filterable paths, caveats, per-year coverage, source health, dump URLs). This helps agents decide whether to pass a dataset or omit 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 clearly names the resource ('Market Trackers catalog') and the action ('Lists'), and enumerates the dataset types and returned metadata (row count, freshness, years, ticker-searchability). It also references trackers_query, letting an agent distinguish this discovery tool from the query tool without opening the schema.

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

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

It explicitly states when to pass the optional dataset ('Pass dataset for the full field roster...') and instructs agents to 'read it before composing trackers_query filters', giving a concrete precondition for using a sibling tool. This provides clear routing without ambiguity.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it reveals the underlying data source (the dumps' latest.json), the meaning of 'latest' (last daily publish), and a major availability limitation for patents. It does not detail pagination or return shape, but the annotations already establish safety and volatility.

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

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

Three sentences, each adding value: a precise definition, a use-case illustration, and an exclusion with a fallback. The 'cheapest way' phrase is a bit promotional but still communicates intended use.

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

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

For a complex 8-parameter tool with no output schema, the description supplies the key usage context, the semantic of 'latest', and the critical patent exclusion. It does not describe result fields, but the schema is thorough and the rows return shape is inferable.

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 each parameter is well documented in the schema. The description only summarizes the ticker/text filters and points to textPaths in trackers_datasets, adding little 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 exactly what the tool returns: the newest ingestion day's rows from the last daily publish, optionally filtered by ticker or text. It also distinguishes the tool from the trackers_query sibling by explicitly excluding snapshot-only datasets.

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 clear use case ('the cheapest way to see what is new') and an explicit when-not-to-use with the alternative: 'Not available for snapshot-only bulk datasets (patents); use trackers_query there.' This is strong routing guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds substantial behavioral context beyond annotations: year-sharded CC0 dumps, the default to the newest year, the byte-budget refusal mechanism, and the provenance field (sourceUrl). It also warns about the cost of deep-history years. This is rich behavioral disclosure that goes far 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?

The description is a single well-organized paragraph that front-loads the core purpose, then adds operational details (year sharding, byte budget, provenance), and concludes with three concise examples. Every sentence contributes value, and the structure makes it easy to scan.

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

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

Despite 11 parameters, nested objects, and no output schema, the description covers essential call context: data source, filtering options, paging/ordering, byte-budget constraints, and provenance. It includes enough examples to guide an agent in common use cases. Nothing critical is missing for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100% for all 11 parameters, so the baseline is 3. The description adds meaningful semantic context: it explains how `years` and `since`/`until` interact with the sharded dumps, advises on deep-history years, and illustrates `where` with concrete examples (e.g., {code: 'P'}). It also clarifies that `ticker` only applies to tickerSearchable datasets. This elevates it above baseline.

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

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

The description opens with a specific verb and resource: 'Search one Market Trackers dataset' and enumerates the search dimensions (ticker, free text, exact field values, event-date range, paging, ordering). It clearly differentiates from sibling tools like trackers_datasets (metadata), trackers_latest, and trackers_ticker by focusing on dataset-wide search.

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

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

The description gives explicit usage guidance on year selection, including the byte-budget refusal and advice to read deep-history years one or two at a time. It provides three concrete examples (insider purchases, senator trades, lobbying filings) that map search patterns to datasets and filters. However, it does not explicitly contrast with sibling tools or state when NOT to use this tool, though the examples imply the appropriate scenarios.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds meaningful behavior beyond that: it returns per-dataset match counts plus newest rows, and discloses that oversized deep-history archive years are skipped and readable via trackers_query. It could mention limits or error behavior, but this is solid supplemental disclosure.

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

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

The description is dense but well-organized: core scope first, then dataset enumeration, then return shape, then the skipped-years behavior. The dataset list is long but earns its place by defining the tool's breadth. No redundant filler; the only slightly extraneous phrase is 'a public-record dossier from primary sources,' but it adds useful framing.

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 does well to explain the return shape (per-dataset match counts and newest rows) and the skipped-archive handling. It covers defaults and the sibling tool for deep history. It doesn't specify exact output formatting or failure cases, but for a read-only fan-out tool the essential expectations are present.

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

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

Schema description coverage is 100%, so the schema already documents ticker, year, limit, and context. The description reinforces the year default and hints at the limit concept via 'newest rows of each,' but it doesn't add significant parameter-level detail beyond the schema. A 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 description opens with a specific verb and resource: 'One ticker across every ticker-bearing Market Trackers dataset for one year.' It enumerates the dataset categories and states exactly what is returned (per-dataset match counts with newest rows). This clearly distinguishes it from siblings like trackers_query, trackers_latest, and trackers_datasets.

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

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

The description gives concrete usage context: it defaults to the current year and covers a broad one-ticker scan across many datasets. It also names the alternative for skipped deep-history years ('listed under skipped with the trackers_query call that reads them'). It doesn't explicitly contrast with trackers_latest or trackers_datasets, but the ticker-scoped fan-out purpose is clear enough.

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