SignalDock

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

With readOnlyHint, idempotentHint, non-destructive and closed-world already supplied by annotations, the description still adds real value: it declares the consent and API-allowance gates and enumerates the side effects it explicitly does not perform (no saving, no order placement, no broker sync). It does not describe response shape, rate limiting, or what happens when the 50-holding cap is exceeded, so it is not fully transparent.

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 compact sentences with the operation and its input contract front-loaded, followed by prerequisites, then exclusions, then the sibling pointer. Every sentence carries information; the only mild redundancy is the closing clause about accepting the existing stock-holdings contract, which restates the opening.

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 five-parameter tool with a nested holdings array and no output schema, the description covers preconditions and side-effect boundaries but never indicates what the analysis returns or how limit/offset/path affect results. The undocumented benchmark parameter is the largest gap, since its intent (comparison index) is not obvious from the schema alone.

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

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

Schema description coverage is only 20% (only 'path' is documented), so the description carries most of the burden. It explains the holdings contract well (symbol, shares, optional cost basis, max 50 items) but says nothing about benchmark, limit, or offset, leaving three of five parameters to inference. That partially compensates for the coverage gap but does not close it.

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

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

The description states a specific verb and resource ('Run the existing Portfolio API for up to 50 supplied stock holdings with shares and optional per-share cost basis'), which tells an agent exactly what is analyzed and the shape of the input. It also distinguishes itself from the sibling read_portfolio by noting that saved option holdings are read there, not here. Naming the operation as an API passthrough is slightly indirect but not confusing.

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?

Prerequisites are explicit ('Requires portfolio consent and existing service access/API allowance'), and the exclusions are spelled out: it does not save a portfolio, place orders, or synchronize a broker, and read_portfolio is the alternative for saved option holdings. What's missing is a positive when-to-use statement for ad-hoc supplied holdings versus analyzing saved data, though it is strongly implied.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds the useful account-connection prerequisite, but says nothing about pagination behavior (limit/offset), the field-directory path semantics, or what the analytics payload contains.

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

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

Two short sentences with no padding, and the prerequisite is front-loaded ahead of the purpose. Efficient, though the ordering means the actual function is stated second.

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 5-parameter tool with 20% schema coverage and no output schema, the description leaves too much unexplained: symbol format, what limit/offset paginate, how 'path' selects a root of the returned field directory, and what the analytics result looks like.

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

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

Schema description coverage is only 20%: only 'path' is documented, while symbol1/symbol2, limit and offset have no schema descriptions. The description implies the two symbols are securities but never states the ticker format (the regex allows optional leading slash and 20 chars) or what limit/offset govern.

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 ('Read') and a specific resource ('correlation, relative action and divergence analytics for two distinct securities'), which is clearly different from siblings like analyze_portfolio or research_company. The phrase 'relative action' is vague jargon, but the core comparison purpose is unambiguous.

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

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

The only guidance is a prerequisite ('Requires a SignalDock account connection'). There is no statement of when to prefer this over research_company, analyze_portfolio, or read_report, and no exclusions or conditions for use.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and a closed-world scope, so the safety profile is covered. The description adds behavior the annotations cannot: pagination is snapshot-bound (page 1 must be reused for later pages) and results are descriptive rather than predictive. It still omits the cost/size characteristics of an 11-parameter, likely wide result set.

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

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

Three short sentences, no filler, and the operational rule (snapshot reuse) is stated plainly. The opening sentence is dense domain jargon ("provenance and coverage") that costs more parsing effort than the space it saves, but overall sizing is appropriate.

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

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

For an 11-parameter tool with 9% schema coverage and no output schema, the description should carry much more: it never clarifies the duplicated paging controls, the two symbol parameters, or what fields the returned directory exposes. An agent must guess at most parameters before its first 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 9% — only "path" is documented — and 11 parameters exist with none required. The description explains only the snapshot parameter's provenance role; symbol vs target_symbol, season format, the date range, and the overlapping limit/page_size and page/offset controls are left entirely unexplained in both schema and 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?

"Retained earnings events and sector × market-cap comparisons" names the resource and the two content modes, but there is no verb and no statement of what is actually returned (a list of events? a comparison table?). An agent cannot tell from this sentence how earnings_history differs from siblings like research_company or compare_symbols.

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

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

The only procedural guidance is "For page > 1 reuse the snapshot returned on page 1", which is genuinely useful usage instruction, and the closing caveat implies the tool is for descriptive reading. There is no when-to-use / when-not-to-use versus the sibling research and comparison tools, and no guidance on when to pass symbol versus target_symbol.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds real behavioral context the annotations cannot: a hard budget of at most five provider operations, an explicit precondition (expiration for skew/activity) that the enum schema does not enforce, and a data-quality caveat that coverage is bounded and never whole-chain totals. It stops short of describing pagination or the shape of the response.

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 short sentences, each carrying distinct information (prerequisite, outputs, quota, conditional requirement, caveat), with nothing padded. The telegraphic style — fragmented noun phrases like 'Expected move, near-money skew/activity or IV history' — trades a little readability for density.

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

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

For an 8-parameter, no-output-schema tool in a specialized domain, the description covers purpose, prerequisites, operation budget, and coverage limits well. It is incomplete on how history_days and strike_count shape results and on whether limit/offset/path imply a paged field-directory response, which an agent would need before invoking it reliably.

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

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

Schema description coverage is only 13%, so the description must carry weight. It does explain the central 'question' enum values and the conditional expiration requirement, but leaves history_days, strike_count, path, limit, and offset undefined; limit/offset/path are plausibly generic pagination, yet the domain-specific numeric parameters remain unexplained in both schema and 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 names the concrete outputs (expected move, near-money skew/activity, IV history) and the scope (one equity or futures root), which is enough to distinguish it from bulk siblings like read_options_history. It is delivered as a noun phrase rather than an explicit verb, so the 'what it does' is inferred rather than stated, keeping it just short of a 5.

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

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

It gives useful preconditions — a SignalDock account connection is required, and skew/activity require an expiration — but it never says when to pick this over read_options_history, compare_symbols, or research_company. Usage is implied by the listed question types rather than contrasted against alternatives.

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

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

Annotations already cover read-only, idempotent, and closed-world behavior, so the baseline is low. The description adds genuinely new context—dual consent requirements and owner-scoped data isolation—but says nothing about pagination behavior or what the 'field directory' projection actually does.

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

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

Three short sentences, content front-loaded, and the consent/scope constraints are placed after the payload listing. Nothing is redundant, though the scope sentence could be merged more tightly with the consent sentence.

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

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

With no output schema and a low-coverage input schema, the description should explain the field-directory projection and pagination model that the 'path' parameter implies. It covers the content and access model well but leaves the mechanics of retrieval entirely undocumented.

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

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

Schema description coverage is only 33%: 'path' is documented but 'limit' and 'offset' have no descriptions. The description does not compensate at all—it never mentions projection paths, page size, or offset semantics, so an agent must guess how to traverse a large context.

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

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

Names a specific verb ('Read') and enumerates the returned content: watchlists, symbols, service access, and broker portfolio summary. It is largely distinguishable from siblings, though 'saved broker portfolio summary' overlaps conceptually with read_portfolio and the description does not clarify the boundary.

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 prerequisite ('Requires both Workspace and portfolio consent') is stated, which helps an agent decide whether it can run at all. However, there is no explicit guidance on when to use this versus read_workspace or read_portfolio, leaving the sibling routing to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety bar is low. The description adds meaningful context beyond that: the access requirement and the fact that archived snapshots are read as-is rather than regenerated, which shapes expectations about staleness.

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

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

Three short sentences, front-loaded with the two operating modes, then the access prerequisite, then the negative constraint. No redundant or filler wording.

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 and 25% parameter coverage, the description leaves the agent guessing about pagination behavior for the date-listing mode and about what a snapshot read returns. It covers the core modes and access requirement but not the full call surface.

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

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

Schema coverage is only 25% — only `path` is documented. The description implies that omitting `date` lists available archive dates and supplying it reads that snapshot, which adds real meaning. But limit/offset pagination semantics are left entirely to the bare schema.

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

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

Description states two specific modes with concrete verbs and resources: listing retained daily archive dates, and reading a saved daily snapshot. This distinguishes it from read_report (fresh reports) reasonably well, though it never names that sibling explicitly.

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

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

It gives a prerequisite ('Requires account research access') and a negative constraint ('Does not regenerate reports'), which implies the agent should look elsewhere for fresh report generation. However, no sibling tool is named and there is no explicit when-to-use-this-vs-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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description contributes the authorization precondition ('Requires account research access'), which the annotations cannot express. It does not explain pagination behavior or what happens with an invalid/expired identifier — meaningful gaps for a paged read.

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

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

Two short sentences, zero filler, and the key dependency (identifier from options_question) is front-loaded alongside the action. Nothing to remove.

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 four-parameter read with no output schema, the definition covers what it is, where the identifier comes from, and the access requirement. The remaining gap is the semantics of limit/offset relative to path traversal, which an agent would need to guess.

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

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

Schema coverage is only 25%: only 'path' is documented in the schema, and the description clarifies the required 'snapshot' parameter as an identifier produced by options_question, which is genuinely useful meaning beyond the bare string type. However, 'limit' and 'offset' are undocumented in both places, and their interaction with 'path' paging is left ambiguous.

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

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

States a specific verb and resource ('Read a retained options-history snapshot') and ties the input to a sibling's output ('using the identifier returned by options_question'), which separates it from the sibling that produces that identifier. It stops short of describing what the snapshot contains, so it is clear but not maximally distinguishing.

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

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

Gives a clear precondition for use — you must already have an identifier from options_question — and names the access requirement. It does not state when not to use it or what to do if the snapshot is stale or expired, so there is no explicit exclusion guidance.

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

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

Beyond the annotations, it discloses consent requirements, that data comes from saved dated snapshots, and that no broker synchronization or imports occur. It also mentions pagination via nextCursor for list/history pages, though it does not explain failure behavior when consent is missing.

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

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

Three tight sentences, front-loaded with the main purpose and followed by constraints and pagination guidance. There is no redundant wording or filler.

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

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

The description adequately covers the tool's high-level scope, safety constraints, and snapshot-based behavior. However, with seven parameters and low schema description coverage, an agent still lacks enough parameter semantics to invoke all action modes confidently, even though no output schema is 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 only 14%, and the description explains almost none of the seven parameters. It mentions pagination for list/history pages, but does not clarify action modes, source_id, analysis_id, limit, offset, or how cursor differs from nextCursor.

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 specific verbs (list, read) and concrete resources (portfolios, holdings, balances, performance, analysis history), making the tool's scope clear. It also distinguishes itself from an analysis-generation sibling by stating that it never generates a narrative.

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

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

It gives clear usage context: requires portfolio consent, uses saved dated snapshots, and explicitly excludes synchronization, imports, order placement, and narrative generation. It does not name the best alternative for narrative or analysis generation, but the exclusions are strong 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real context beyond them: no auth required, that oversized responses return a field directory rather than the data, and that the tool has no generate/email side effects. It stops short of describing what a typical report payload looks like.

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

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

Three short sentences, front-loaded with the core capability, then the large-response mechanism, then the boundary. Nothing is repeated from the title or schema and no sentence is filler.

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

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

For a seven-parameter read tool with no output schema, the description covers the two things an agent most needs: auth-free access and the field-directory/path indirection for large payloads. The remaining gap is what a report actually contains and whether limit/offset apply uniformly across all fifteen report types.

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 57%, so several parameters (limit, offset, report enum values) carry no inline description. The description compensates by explaining the paging model ('select a path and page arrays'), which is what path/limit/offset/before jointly implement, and by stating the count of fifteen reports behind the enum.

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 concrete verb and resource ('Read one of fifteen published market reports') and bounds it with an explicit non-capability ('Never generates or emails a report'). It's clear what it does, though it doesn't explicitly contrast with near-neighbors like read_archive or read_workspace, leaving the agent to infer which read tool fits.

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 useful operational guidance ('without signing in', 'select a path and page arrays') and one exclusion (no generation or emailing). It never says when to pick this over read_archive or read_workspace, so routing among the read_* siblings remains inferred.

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds real value with the consent requirement and the clarification of what "Trades" means, but it says nothing about the return shape or the field-directory navigation that the path parameter implies.

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

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

Three short sentences with the resource scope front-loaded first, followed by the consent prerequisite and then the negative constraints. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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

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

For a read tool with no output schema and four parameters, the description covers scope, consent and semantic disambiguation well. However, it omits how pagination (limit/offset) behaves and how the path drill-down works against the returned field directory, both of which an agent needs to use 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 coverage is only 25%: path is documented in the schema while limit, offset and section carry no description. The description adds no parameter guidance at all, and critically never explains the two-step pattern implied by path ("Object keys or array indices from the returned field directory"), which an agent must understand to traverse results.

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

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

"Read your saved Rules, Notes and Trades from Playbook, or your saved Security Snapshot" gives a specific verb plus an enumerated set of resources, and the clarification that Trades are written strategies rather than brokerage executions implicitly steers the agent away from read_portfolio. No sibling is named outright, so the differentiation is inferred rather than stated.

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

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

The description sets a clear precondition ("Requires explicit Workspace consent") and an explicit negative scope ("Never edits content or generates/emails reports"), which routes report generation to read_report. It stops short of naming which sibling to call instead for portfolio or archive data, leaving some inference to the agent.

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

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

Beyond the read-only and non-destructive annotations, the description discloses the SignalDock account prerequisite, coverage limited to existing API data, missing-data warnings, and the important distinction between pending and completed analysis. It would be stronger if it explained how a pending analysis is subsequently retrieved or completed.

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

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

The description is compact and front-loads the connection prerequisite, followed by scope and two important result caveats. Each sentence contributes distinct operational information without unnecessary wording.

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 definition is minimally sufficient to attempt a call using the required symbol and section fields, and it communicates important partial-data and pending-state behavior. Nevertheless, the lack of an output schema and low parameter documentation leave gaps around section selection, response navigation, pagination, and pending-result follow-up.

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 only 20% schema description coverage, the description needed to compensate more substantially. Its topic list loosely clarifies the six section choices, but it does not explain the symbol format, section-to-topic mapping, path navigation, or how limit and offset affect returned data.

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?

Together with the title, the topic list makes clear that the tool researches a security across technical analysis, forecasts, estimates, earnings, valuation, and capital structure. It does not distinguish this broad research tool from siblings such as earnings_history, compare_symbols, or read_report.

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

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

The account-connection prerequisite and research-topic list imply appropriate use cases. However, there is no explicit guidance on selecting a section, when not to use the tool, or which sibling to use for narrower requests.

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 real value by disclosing that updates and fills are a narrative simulation and no orders are placed. The annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description is silent on pagination behavior, what a bare call returns, and how to discover available days.

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

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

Two sentences, front-loaded and free of filler. The only cost is that combining two distinct modes in one clause reads slightly awkwardly.

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, and the description never explains the shape of the returned feed or the "field directory" that `path` indexes into. Pagination semantics and how the available-days list is obtained are also missing, which leaves too much unexplained for a tool with four parameters.

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

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

Schema description coverage is only 25%; only `path` is documented. The description does not explain `date` (does it select one day's feed?), `limit`, or `offset`, so it fails to compensate for the schema gap, even though `date` determines which of the two modes runs.

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

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

The description uses a specific verb and resource: "Read the public Trading Agent day feed or list available days." This distinguishes the tool from its siblings (read_archive, read_portfolio, read_report), but the dual purpose is not resolved; it never says which mode is active when `date` is absent.

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 supplies one useful constraint: public history starts November 1, 2026. However, it gives no when-to-use guidance, no explanation of when to supply `date` versus omit it, and no reference to alternative tools for related needs.

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