Gloom

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real value beyond that: the 'Pro:' tier signal and the caveat that rankings are not downloads or revenue and that absent/unavailable charts remain unknown, which sets correct expectations about data meaning and gaps.

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

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

It is compact and front-loads the returned data categories, with the operational hint and the semantics caveat following. Sentences are dense with information, though the 'Pro:' fragment is slightly cryptic and no words are wasted overall.

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 usefully enumerates the return categories, which covers the output side reasonably. But for a 6-parameter query tool with 0% schema coverage and no annotations on parameters, the near-total silence on days/chart/limit/offset leaves the definition incomplete for correct invocation.

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

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

Schema description coverage is 0%, so the description carries the burden of explaining the six parameters, yet it only touches symbol (omit for global) and gestures at country via 'country spreads'. days, chart, limit and offset are entirely unexplained, leaving the agent to guess at their semantics despite the tool documenting them nowhere else.

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 enumerates the specific data the tool returns – app chart rank, rank velocity, rating-count growth, country spreads, ownership mapping, source evidence – so an agent knows it is an app-attention data query. It is clear and specific, but never names or contrasts itself with close siblings like apps.rank_history or market.attention, so sibling differentiation is missing.

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

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

It provides one concrete usage directive – 'Omit symbol for the global board' – which tells the agent how to switch between scoped and global queries. However, there is no guidance on when to choose this tool over apps.rank_history or market.attention, and no prerequisites or exclusions, so usage is only partially 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 openWorld, so the safety profile is covered. The description adds real interpretive context beyond that: confirmed chart exits are returned as nulls rather than omitted, revisions are immutable with primary-source provenance, and missing collection dates are gaps rather than zero values. This meaningfully changes how an agent reads 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?

A single dense sentence, front-loaded with the purpose, followed by qualifying clauses that each carry distinct information. The 'Pro:' prefix is slightly odd but does not waste much space.

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 seven parameters, no output schema, and no schema-level documentation, the description should do more to explain pagination (limit/offset) and the days window. It covers result interpretation well but leaves invocation semantics incomplete.

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

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

Schema description coverage is 0%, so the description carries the full burden. It references country/chart/depth identity and maps loosely to appId/store, but says nothing about days, limit, offset, or how country/chart filter the series. Four of seven parameters remain semantically unexplained.

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

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

States a specific verb+resource: retained daily ranks and ratings, scoped to a single App Store ID or Google Play package. An agent can tell it retrieves historical rank/rating data for one app. It does not name or contrast with the sibling apps.attention, so it falls short of full sibling differentiation.

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

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

No when-to-use guidance, no alternatives named, and no conditions that select this tool over apps.attention or market.history. The agent must infer usage entirely from the purpose sentence.

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 cover safety traits (read-only, idempotent, non-destructive, open-world). The description adds meaningful behavioral context beyond them: cursor persistence, following `hasMore`, and handling revisions with identical timestamps.

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 tightly packed sentences: purpose first, then pagination guidance, then a source-date caveat. Every sentence adds operational value with 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 some return-value burden and does mention `nextCursor` and `hasMore`. It is still incomplete for a change-feed tool because it does not describe the response item shape or the `limit` parameter.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies `since` as an ISO timestamp and implies the cursor usage via `nextCursor`/`hasMore`, but it does not describe the `limit` parameter or fully explain the input cursor token.

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 content and ordering of the feed: chronological first observations and status/date revisions since an ISO timestamp. It is clear enough about the resource, though it does not explicitly name or differentiate from the sibling catalyst event feed.

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 implies usage through the required `since` timestamp and gives pagination guidance. However, it does not state when to use this change feed instead of alternatives such as `catalysts.event`, leaving sibling selection 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 and openWorld, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: revisions are immutable, each carries an observation time and a predecessor pointer, and quotes are literal. It omits pagination behavior for the limit/offset parameters but does not contradict anything.

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-loading the purpose before the prerequisite and the revision semantics. No filler or repetition 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 lookup tool with no output schema, the description covers what the resource is, where the id comes from, and what a revision contains. The only real gap is pagination semantics for limit/offset, which leaves an agent guessing about default result volumes.

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

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

Schema description coverage is 0%, so the description must compensate. It does explain the critical 'id' parameter (stable id from market.catalysts or company.litigation), but says nothing about limit or offset, leaving two of three parameters undocumented in both schema and prose. Baseline 3 reflects partial compensation.

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 ('Inspect') and resource (a calendar event's immutable revisions and literal source quotes), which is concrete and non-tautological. It does not, however, differentiate itself from the sibling catalysts.changes, which an agent might reasonably confuse with this history/revision 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?

'Use the stable id returned by market.catalysts or company.litigation' gives explicit prerequisites and names the producing tools, which is strong routing guidance. It stops short of 5 because it never states when NOT to use this tool or how it relates to catalysts.changes.

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 the write/destructive/non-idempotent profile, so the bar is lower, and the description still adds real value: it discloses the upsert behavior and, critically, that omitted fields are cleared ("clearing either one left out"). The only quibble is a slight tension with idempotentHint=false, since a replace-or-add of the same payload yields the same state, but the description is not contradicting the annotation outright.

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 zero filler; the core write/upsert behavior leads, followed by the two field caveats. 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 6-parameter mutation with no output schema and very low schema coverage, the description covers the upsert and clearing semantics plus two field meanings, which is the most important information. It still omits exchange/collectionId semantics and any auth or error behavior, so it is adequate but with clear gaps.

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

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

Schema coverage is only 17% (just teamId is documented), so the description should carry more. It does add meaning for quantity (portfolio-only) and note (short label, not research), but leaves exchange — a semantically ambiguous field that affects how a holding is matched — and collectionId entirely unexplained.

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 ("Writes one item to a team collection") and immediately clarifies the upsert scope: adds the symbol or replaces the quantity/note of an existing entry. This is clearly distinguishable from sibling read tools (collections.get, collections.list) and from collections.remove_symbol, without needing to name them.

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

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

Usage is implied by the semantics: use this to add or update a single collection item, and "Quantity only applies to portfolios" scopes one field's applicability. The line "The item note is a short label, not research" implicitly routes research content elsewhere (e.g. notes.save), but no alternative is named and there is no explicit when-not-to-use or prerequisite 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, idempotentHint, non-destructive, and non-open-world, so the description's 'Read-only:' prefix is largely redundant. It does add genuine value by describing the per-item content returned (symbol, exchange, quantity, note), which is useful given there is no output schema, but it omits pagination (limit) and any auth/team-pinning behavior.

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

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

Single efficient sentence, front-loaded with the read-only nature and the resource, with the return-field enumeration tacked on. No wasted words, though it is arguably under-specified rather than tight.

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

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

With no output schema, the description usefully sketches return fields, and annotations cover the safety profile. However it leaves the required collectionId and the limit/pagination semantics unexplained, which is a meaningful gap for a 3-parameter 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 only 33% — only teamId is documented in the schema. The description does not explain collectionId (the required parameter) or the limit parameter, so it fails to compensate for the coverage gap.

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

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

States a specific verb ('Read') and resource ('the items in one team collection'), and goes further to enumerate the returned fields (symbol, exchange, quantity for portfolios, note). The phrase 'one team collection' distinguishes it from the sibling collections.list, which enumerates collections themselves.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no named alternatives (e.g., collections.list for the collections themselves, or portfolio.positions for holdings). Usage is only weakly implied by the resource being described.

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 openWorldHint=false, so the description repeats 'read-only' unnecessarily. It does add real behavioral context the annotations lack: omitting teamId widens the result set to every team the key can reach, which is a scope side effect an agent must anticipate.

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

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

A single well-formed sentence with the read-only nature and the two scope branches front-loaded. Nothing is wasted and 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 returns; it names the listed entities but omits pagination/limit behavior, ordering, and whether collection contents are included. Adequate to call the tool, incomplete for predicting 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 only 50%: teamId is documented in the schema, while limit has no description anywhere. The description elaborates the teamId omission case but says nothing about limit, its default of 100, or its 200 maximum, so the coverage gap is not compensated.

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 (list) and resource (watchlists and paper portfolios) and clarifies the two scopes: one team, or all reachable teams when teamId is omitted. The 'list' vs 'get' contrast with collections.get is inferable from the verb, but no sibling is named explicitly.

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

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

States the condition that changes behavior (teamId omitted) but gives no explicit guidance on when to prefer this over collections.get, nor any prerequisites or exclusions. Usage is implied rather than directed.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the agent knows this is a destructive but repeatable write. The description adds only the small scope detail that a single item (not a bulk set) is removed; it says nothing about irreversibility, auth requirements, or side effects on the team collection.

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

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

A single front-loaded sentence with zero filler, which is structurally clean. However, for a 4-parameter destructive tool it is arguably undersized rather than appropriately concise, pushing useful detail out of the definition.

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

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

There is no output schema and no information about return values, error cases, or the required collectionId/symbol pairing. Combined with 25% schema coverage and limited guidance, the definition is not complete enough for an agent to call this destructive tool confidently.

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% — just teamId carries a description explaining it comes from teams.list and is optional when the key is pinned to a team. The description compensates for none of the undocumented parameters (symbol, exchange, collectionId), leaving their format and optionality unclear.

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 ("Deletes") and resource ("one item from a team collection"), and the pairing with sibling collections.add_symbol makes the inverse operation obvious. The wording is slightly generic ("item" rather than "symbol") and does not name the sibling explicitly, so it falls short of a 5.

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

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

The description gives no when-to-use guidance, no prerequisites, and no named alternative. The symmetric add_symbol sibling is left for the agent to infer; nothing says when removal is appropriate versus updating the collection another way.

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, idempotentHint=true, and destructiveHint=false, covering safety and idempotency. The description adds context about the data categories returned but does not disclose pagination behavior, rate limits, or how the limit parameter affects results. It is consistent with annotations, so no contradiction, but it provides limited additional behavioral insight beyond the listed data.

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, front-loaded sentence with no redundant words. It immediately states the purpose and enumerates the outputs efficiently, making it easy to parse and act upon.

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 tool with robust annotations, the description provides enough to understand what data is returned, but it omits how the limit parameter applies across multiple data types and does not mention exchange disambiguation. Since there is no output schema, a brief note on return structure would improve completeness, but the description is adequate for basic use.

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

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

Schema description coverage is 67% (symbol and exchange have descriptions; limit lacks a description but has constraints). Since coverage is moderate, the description should compensate by explaining parameter usage, but it does not. The description mentions the data categories but not how limit or exchange interact with the query, leaving agents to infer from schema defaults and bounds.

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 'Get' and a clear resource 'analyst research' while enumerating the exact data categories (price targets, recommendation trends, rating changes, earnings estimates, revenue estimates). This level of specificity distinguishes it from sibling tools like company.financials or company.statements, making the purpose unambiguous.

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

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

The description implies usage when analyst research data is needed, but it does not explicitly mention alternatives or conditions when this tool should not be used. It lacks guidance on when to prefer this over similar tools like company.financials or market.quotes, though the specificity of the data types gives some implicit 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 readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds that revisions are 'preserved' and evidence is 'primary-source', but says nothing about pagination, result size, or how revisionsCursor behaves, which matters for a tool with a cursor parameter.

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, front-loaded with the resource list and followed by the id-sourcing instruction. No filler; every clause carries information.

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

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

With no output schema, the enumerated evidence categories usefully stand in for what gets returned, and annotations cover safety. The one gap is the unaddressed pagination cursor, which an agent would need to know about to fetch all revisions.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the origin and format expectation of 'id' (the exact id returned by company.awards), which is genuinely useful beyond the regex pattern, but it never mentions or explains revisionsCursor, leaving half the parameters undocumented.

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 (Read) and enumerates the exact resource set: preserved revisions, subcontractors, modifications, government-customer edges, and primary-source evidence. The line 'Use the exact id returned by company.awards' implicitly distinguishes it from the awards-list sibling, though it never names what this tool is not.

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: obtain the exact id from company.awards first, which is the practical entry point for this evidence tool. It does not state when to prefer or avoid it relative to other award-adjacent siblings, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world, so the safety profile is covered. The description adds real value beyond that: it discloses data provenance (verified ticker matches, source links, exact currency amounts) and a substantive semantic warning that cumulative awards are not accounting backlog and that lifetime obligations differ from transaction flows.

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

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

Three sentences, front-loaded with the resource and its enriched fields. The listing of dimensions is dense but purposeful, and the final contrast sentence earns its place as a genuine usage caveat. Slightly overstuffed 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?

With 15 parameters, no required fields, no output schema and zero schema descriptions, the definition should do more to explain pagination (limit/cursor), date-range semantics, and the query/source/parentId inputs. It covers the domain concept well but leaves enough operational detail unspecified that an agent may construct a suboptimal 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 0% across 15 parameters, so the description carries the full burden. It hints at the ticker, jurisdiction, awardType (prime/subawards/modifications), agency, sector, and currency dimensions, but leaves from/to, limit, cursor, query, source, parentId, minAmount, and fiscalYear completely unexplained anywhere, which is a major gap for an agent building a correct call.

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 resource and scope: government prime awards, subawards, modifications, plus the enrichment dimensions (ticker matches, source links, agency concentration, sector rankings). An agent can tell what data it returns. However, it never names or distinguishes itself from the sibling company.award_evidence, so sibling differentiation is left to inference.

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?

'Filter by ticker or jurisdiction' gives an implicit pointer to the primary filtering mode, and the closing note signals a semantic caveat about lifetime obligations vs. transaction flows. But there is no explicit when-to-use guidance and no stated alternative such as company.award_evidence, so usage is only implied.

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

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

Annotations already establish that the tool is read-only, idempotent, and non-destructive. The description adds no behavioral context beyond naming the 'shared market-data service' as the source; it does not mention response size, data freshness, rate limits, or the fact that this is an aggregate call.

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

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

The description is a single, front-loaded sentence that lists the tool's outputs without any filler or repetition. Every phrase contributes to defining the tool's scope.

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 aggregate data tool, the description identifies the key output categories and the schema defines the parameters. However, since there is no output schema, the description could usefully explain how the returned quote, profile, fundamentals, and statements are grouped or limited by the `limit` parameter.

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 67%, with symbol and exchange already described in the schema. The description does not add meaning for the `limit` parameter or explain how it interacts with the annual/quarterly statements it mentions, so it fails to compensate for the one parameter not fully covered by 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 uses a specific verb ('Get') and enumerates the resources returned: quote, profile, fundamentals, and annual/quarterly statements. This makes the tool's purpose clear, though it does not explicitly distinguish it from closely related siblings like company.profile and company.statements.

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

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

The description gives no guidance on when to use this tool versus alternatives such as company.profile, company.statements, or market.quotes. It merely states what is returned, leaving the agent to infer when the aggregate 'financials' call is the right choice.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real context beyond them: results are 'cited' (evidence included) and numeric direction is kept separate from economic beat/miss. It still says nothing about pagination, the limit cap, or the effect of includeRevisions.

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 dense sentences with no filler; the core resource content is front-loaded and the separation caveat follows. It is efficient, though the second sentence's meaning is not fully self-evident.

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, filter-heavy tool with no output schema and no per-parameter documentation, the description is too thin: it never explains the date filters, the limit cap, metric matching, or revision behavior, leaving an agent unable to invoke it accurately beyond the required symbol.

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

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

Schema description coverage is 0% across 8 parameters, so the description carries the full burden. It only loosely gestures at the accounting 'basis' enum ('currency, scope and accounting basis') and at date concepts, leaving from/to/asOf semantics, limit, metric, and especially includeRevisions completely undefined.

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 precisely characterizes the resource: cited management guidance ranges, issue dates, raises/cuts versus prior guidance, and later actuals on matching period/currency/scope/basis. It is clearly a guidance-history read tool, but it never contrasts itself with siblings like company.financials or company.kpis, so the agent gets no explicit disambiguation.

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

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

There is no when-to-use, when-not-to-use, or alternative-tool guidance anywhere in the text. The agent must infer the use case entirely from the resource description.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows the tool is safe and read-only. The description adds the fact that data is 'Collected daily by Gloomberb,' which gives freshness context. It does not mention any limitations, rate limits, or response format. Since annotations cover the safety profile, the description provides marginal additional value beyond 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 a single sentence that front-loads the core action ('Read one company's hiring picture') and then lists the key data dimensions. It is efficient and not verbose, though the enumeration is a bit dense with commas and 'and.' It is appropriately sized for the tool'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?

The description gives a good overview of the output categories (open roles, function, country, seniority, posting age, pay ranges, theme signals, newest roles), which is helpful given there is no output schema. However, it does not explain the 'roles' parameter's effect on the output, nor does it mention any pagination or data structure details. While it covers the main dimensions, it leaves a gap around parameter behavior, so it is only partially complete.

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

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

Schema description coverage is 50%: only 'ticker' has a description. The 'roles' parameter is left undefined in both the schema and the description. The description mentions 'open roles' but does not explain what the 'roles' parameter controls (e.g., number of roles returned). With half the parameters undocumented, the description should compensate, but it does not, leaving the agent to guess the semantics of 'roles'.

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 ('Read') and a specific resource ('one company's hiring picture from its own careers system'), then enumerates the data dimensions (open roles, hiring by function, country, seniority, posting age, pay ranges, theme signals, newest roles). This clearly distinguishes it from siblings like company.profile (general info) and market.hiring_movers (market-level movers), so an agent can immediately tell what this tool does and what it is not.

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

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

The description implies usage for a single company's detailed hiring data, but it does not explicitly state when to use this tool versus alternatives or when not to use it. For example, it does not mention 'for market-wide hiring trends, use market.hiring_movers instead.' The context is clear enough to infer the primary use case, but there is no explicit guidance on exclusions or alternative selection.

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

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

Annotations already provide the read-only, idempotent, non-destructive profile, so the description does not need to restate those traits. It adds a useful caveat about data completeness with 'when available,' but it does not disclose pagination, response shape, or how symbol ambiguity might be resolved. 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 a single sentence with the verb and object front-loaded, followed by useful return-field details. There is no filler or repetition of the tool 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 simple read-only tool with no output schema, the description names the key returned fields and the query target. It omits pagination or limit behavior and does not distinguish it from potentially overlapping holdings tools, but the schema and annotations cover enough for a basic 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?

The description contributes almost nothing to parameter understanding: only 'for a company' loosely maps to the symbol parameter, and limit and exchange are not mentioned. Schema coverage is 67%, but the description does not compensate for the undocumented limit behavior or add meaning beyond the schema.

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

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

The description states a specific action ('List') and a clear resource ('institutional holders for a company'), and it lists the core data fields returned (report dates, shares, values, ownership percentages). It is easy to distinguish from quote or history tools, but it does not explicitly disambiguate from the closely related sibling sec.thirteenf_holders.

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

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

The description gives no guidance on when to use this tool instead of alternatives such as sec.thirteenf_holders or company.profile. There are no preconditions, exclusions, or routing hints, so the agent must infer context from the tool name alone.

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

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

Annotations already declare the safe-read profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description nonetheless adds real behavioral context: revisions are immutable, and "Missing coverage is not zero" warns that absent KPIs must not be read as zero values. It stops short of explaining pagination or the effect of includeRevisions.

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 dense sentences, front-loaded with the returned resource and its characteristics. Every clause carries information; the trailing caveat about missing coverage earns its place. Slightly terse given the number of parameters left undiscussed.

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

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

With 8 parameters, 0% schema coverage, and no output schema, the description should say more about the temporal filters and revision flag. The safety profile is covered by annotations and the null-means-not-zero caveat is valuable, but an agent still lacks enough to invoke the filters confidently.

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

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

Schema description coverage is 0% across 8 parameters, so the description carries the burden. It hints at several params (accounting basis -> basis, fiscal periods -> from/to, immutable revisions -> includeRevisions) but leaves asOf, limit, and the metric identifier format unexplained. It partially compensates, not fully.

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

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

States a specific resource: company-disclosed operating KPI observations, with the fields they carry (fiscal periods, native currency, accounting basis, scope, evidence). This distinguishes it implicitly from siblings like company.financials and company.statements, though it never names an alternative 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?

No when-to-use, when-not-to-use, or alternative-referencing guidance. The agent must infer from the sibling list that financials/statements cover reported financials while this covers operating KPIs. Nothing tells the agent when this tool is the right pick.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description is not obligated to restate it. It adds genuine value beyond that: an enumeration of returned evidence types and, importantly, a liability disclaimer ('Allegations and procedural status are not findings of liability') that shapes how an agent should interpret and report the data. Pagination behavior for limit/offset is not disclosed.

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

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

Three tight sentences, front-loaded with what the tool returns and followed by the interpretive caveat. No filler, though the middle sentence's field enumeration is dense enough that it could be trimmed without losing meaning.

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 usefully enumerates returned fields (jurisdiction, agency, case identifiers, status, dates, parties, source evidence), which is the right call. However, it omits any parameter guidance and pagination semantics for a 3-param tool, leaving the input side under-specified.

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

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

Schema description coverage is 0%, so the description carries the full burden for three parameters, yet it never mentions symbol, limit, or offset. An agent cannot learn from the description what identifier format is expected or that results are paginated. This is a clear compensation 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 names a specific resource (company litigation and antitrust dockets) and a distinguishing mechanism (linked through verified corporate identities), which separates it from generic sibling tools like sec.filings or news.stories. The retrieval verb is implied rather than stated, and it does not explicitly contrast itself with the nearest sibling (sec.filings), so it falls short of a 5.

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

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

There is no when-to-use guidance, no exclusions, and no named alternatives despite ~40 sibling tools that could plausibly overlap (sec.filings, news.stories, catalysts.event). The purpose implies a use case but the agent is left to infer the trigger condition entirely.

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 disclose that the call is read-only, idempotent, and non-destructive; the description adds the specific payload contents (sector, industry, business description). It does not disclose response shape or exact-match failure behavior, but the safety profile is already covered by 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?

One sentence, no filler, and the most decision-relevant facts (what it returns and that the symbol must be exact) come first.

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

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

The tool is simple, annotations cover safety, and the description states the return contents despite the lack of an output schema. It is complete enough for a basic call, though it leaves error/empty-result behavior unspecified.

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

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

Schema descriptions cover symbol and exchange, and the description reinforces the exact-symbol requirement without adding new semantics. The limit parameter is constrained to 1 but has no description, leaving a small gap; with 67% schema coverage this sits at the acceptable 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 names a specific verb ('Get') and a precise resource ('sector, industry, and business description') for 'one exact company symbol.' That scope is enough to separate it from sibling tools like company.analyst_research, company.financials, and market.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 phrase 'for one exact company symbol' implies the intended condition: call this when the agent already has a precise symbol. It does not explicitly name alternatives for symbol resolution (e.g., market.search) or state when not to use this tool, so guidance is only implied.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, and the description adds a useful scoping trait: it loads only statement periods, not unrelated research data. It does not disclose response shape, period ordering, or pagination, but with strong annotations the bar is lower.

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 focused sentence with the key content front-loaded. Every clause earns its place and there is 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?

For a read-only, idempotent call, the description plus schema is minimally usable: symbol is required, period has a clear enum, and annotations cover safety. Yet with no output schema, the description should characterize the result set more (e.g., what a period contains or how limit applies), so clear gaps remain.

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

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

Schema description coverage is only 50% and the free-text description adds almost no parameter meaning. It restates the period enum choices, but it does not explain what 'limit' counts (years vs quarters vs records) or anything beyond schema for symbol/exchange.

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 action and object ('Get annual, quarterly, or both financial-statement periods') and scopes it to a single company. It stops short of explicitly distinguishing itself from closely related siblings such as company.financials, so it is clear but not fully differentiated.

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

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

It gives clear context for use: this returns statement periods for one company and avoids dragging in unrelated research data. However, it does not name alternative tools or spell out when not to use this tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds non-obvious semantics: unconfirmed leads never count as disclosed exposure, and restricted publishers expose only headline/date/link. These are real behavioral constraints beyond the structured fields, though return shape/pagination behavior is not described.

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 dense sentences, front-loaded with the core read action and followed by defaults and constraints. Every sentence carries information; no filler or restatement of the title.

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

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

With no output schema, the description usefully sketches the returned evidence fields and the trust-tier defaults/opt-in model. Combined with annotations covering safety, an agent has enough to call it correctly, though tier enumeration semantics could be tighter.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It maps the default tier set to 'filings, company releases and calls' and explains includeLeads via 'explicit opt-in', but the 'reported' enum value is never addressed and the symbol pattern/format is not discussed, leaving gaps in a 3-param schema.

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

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

States a specific verb ('Read') and resource ('source-attributed company relationships') and enumerates the payload contents (original-language evidence, dates, claim type, corroboration). It is distinguishable from the graph/paths siblings mainly by the evidence/attribution emphasis, though the description never names them explicitly, so it falls short of a 5.

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

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

Gives clear default-scope guidance ('Defaults to filings, company releases and calls') and states the condition for the non-default path ('Unconfirmed leads require explicit opt-in'). It does not state when to prefer this over company.supply_chain_graph or company.supply_chain_paths, so no explicit alternatives are named.

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

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

Annotations already establish readOnly, idempotent, openWorld and non-destructive behavior, so the remaining burden is lighter. The description goes beyond them with genuinely useful interpretation caveats: direction is monotonic seller-to-buyer (or reverse), scores are ranking heuristics, chained percentages are proportional estimates rather than disclosed exposure, and search limits are reported. These warning-style disclosures meaningfully reduce the chance of an agent misreading the output.

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 dense but purposeful sentences with no filler, and the scope ('one to four disclosed hops') is front-loaded. The phrasing is jargon-heavy ('monotonic seller-to-buyer or its reverse'), which slightly taxes readability, but every sentence carries distinct 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 an 11-parameter tool with no output schema, the description does cover per-hop return contents and result-interpretation caveats reasonably well. It nonetheless leaves the bulk of parameter meaning and any sibling routing unexplained, so it is only minimally adequate for a tool of this complexity.

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

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

Schema description coverage is only 9% across 11 parameters, so the description should compensate but mostly does not. It hints that depth spans 'one to four hops,' which loosely maps to the depth parameter, but offers nothing for roles, tiers, minPct, minConfidence, ranking, sources, direction or asOf, leaving the agent to guess at filtering and scoring inputs.

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

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

The description states a specific action (explore) and resource (supply chain hops of one to four degrees), and lists what each hop carries (source tier, reporting company, quote, filing), so the agent knows this is a graph-traversal tool rather than a flat lookup. However, it never distinguishes itself from the very close siblings company.supply_chain_paths and company.supply_chain_evidence, so an agent cannot tell the three apart from this text alone.

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

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

There is no when-to-use guidance, no prerequisites, and no routing to or away from alternatives, despite two obviously related siblings (supply_chain_paths, supply_chain_evidence). The agent is left to infer the selection criteria entirely on its own.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), yet the description adds genuinely useful caveats beyond them: scores are ranking heuristics, chained percentages are proportional estimates rather than disclosed exposure, and results self-report search limits. This is substantive epistemic context for interpreting output, though auth or rate-limit behavior is not addressed.

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 dense sentences, front-loaded with what the tool returns, then direction, then caveats. Every sentence carries information and there is no padding, though the phrasing is terse enough that it borders on cryptic.

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 12-parameter, no-output-schema tool in a complex domain, the description leaves most of the surface unexplained: the filter semantics, defaults, and result pagination are not covered. It adequately frames the output caveats but not the invocation 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?

With 12 parameters and only 17% schema description coverage, the description must carry parameter meaning but largely does not. It obliquely implies depth ('one to four hops') and direction ('monotonic seller-to-buyer or its reverse'), but the ten undocumented filters (roles, tiers, minPct, ranking, sources, minConfidence, limit, asOf) are never explained.

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

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

The first sentence states a specific operation (explore one-to-four disclosed hops) and the payload per hop (source tier, reporting company, quote, filing), so the agent understands it returns chained supply-chain paths. It does not, however, distinguish itself from the sibling tools company.supply_chain_graph and company.supply_chain_evidence, which likely overlap.

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

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

There is no explicit when-to-use guidance, no prerequisites, and no routing to alternatives, despite two adjacent supply-chain siblings. Usage can only be inferred from the description of the return shape, which is thin given three plausibly interchangeable 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, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful source context ('from periodic transaction reports') and mentions included fields like dates, lag, dollar ranges, and sources, but does not disclose pagination, result limits, or how the openWorldHint affects completeness.

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, front-loaded with the core action and resource, and contains no filler. The second sentence adds useful output context, though it could have been used to clarify parameter behavior instead of listing generic result attributes.

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

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

With 8 optional parameters and no output schema, the description is not complete enough for an agent to predict how filters combine or what the response structure looks like. It conveys the data categories but omits filtering behavior, result shape, and relationship to the sibling Senate 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 only 13%, with only 'ticker' having its own description. The tool description mentions 'ticker and member summaries' but does not explain the semantics of side, year, limit, owner, member, assetType, or minAmount. It therefore fails to compensate for the low 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 ('Get') and names a concrete resource ('House member transactions') plus several specific data categories (ticker and member summaries, stock returns, party, committees). It distinguishes itself from the sibling 'congress.senate_trades' by explicitly targeting House disclosures.

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 usage context is implied by the word 'House' and the sibling congress.senate_trades, which suggests this tool is for House rather than Senate data. However, it never explicitly states when to use this tool versus alternatives or mentions any exclusions or prerequisites.

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 read-only, idempotent, and open-world behavior, and the description adds a valuable non-obvious limitation: paper-filed reports are counted but not read. It also clarifies the data source and what enriched fields are returned. It stops short of a 5 because it does not mention pagination, rate limits, or other potential runtime behaviors.

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 tight sentences with no filler. The first sentence front-loads the action and the key output features, and the second sentence adds the paper-filing caveat. Every part contributes 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 an 8-parameter tool with no output schema and very low parameter coverage, the description gives a helpful summary of returned data and the main caveat, but it does not explain how filters interact or what the response shape looks like. It is adequate for simple calls but not fully complete for nuanced queries.

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 13% schema description coverage, the description needed to compensate for the eight optional parameters, but it does not explain side, year, limit, owner, assetType, or minAmount. It only hints at ticker and member as relevant concepts through 'ticker and member summaries,' which is output-oriented rather than parameter-oriented.

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 'Get senator transactions from electronic Senate periodic transaction reports,' a specific verb and resource that clearly distinguishes this from the House-focused sibling congress.house_trades. It also enumerates the included enrichments such as ticker/member summaries, stock returns, state, party, and committees, making the tool's scope 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 Senate scope and the electronic-report caveat imply when this tool is appropriate, but the description does not explicitly name alternatives or state when not to use it. It mentions that paper-filed reports are counted but not read, which is a limitation, but it never tells the agent to use congress.house_trades for House disclosures.

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 the safe read-only/idempotent profile, and the description adds genuinely useful behavior beyond them: every field carries a primary-source quote and offset (provenance) and headroom is deliberately withheld when definitions cannot be reconciled (a conditional output behavior). These are not restatements of annotations and help the agent trust and 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?

Three tight sentences with no filler, front-loaded on the returned content types. Efficient, though slightly clipped into noun phrases rather than explicit action statements.

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

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

For a single-parameter, no-output-schema read tool, the description adequately conveys what comes back (instrument/covenant/headroom data with provenance) and notes the withholding caveat. It stops short of explaining the symbol argument or differentiating from credit siblings, but is close to complete for this complexity.

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

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

There is one parameter (symbol) with 0% schema description coverage, so the description is expected to compensate but says nothing about it. The symbol parameter is largely self-evident given the domain, but no format or scope detail is added to explain what symbols are accepted.

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 specific content it surfaces (credit instruments, covenants, headroom, native-currency maturity walls), so an agent can tell it returns structured credit data rather than a quote or screen. However, it never distinguishes itself from sibling credit tools like credit.instrument or credit.screen, leaving ambiguity about which to pick.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to or away from the sibling credit.instrument and credit.screen tools. The agent must infer usage entirely from the content list.

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, non-destructive and a closed world, so safety is covered. The description adds the useful content disclosure that superseded amendments are included, but says nothing about permissions, rate limits, or result size; with no output schema it could say more about 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?

Two sentences, no filler, and the payload description is front-loaded before the usage instruction. Every clause 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 two-required-param read with no output schema, the description is adequate but thin: it never defines the symbol parameter or clarifies what 'field evidence' comprises. An agent could call it correctly only by guessing at symbol'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 description coverage is 0%, so the description must carry both parameters and it does not. It implies instrumentId comes from credit.documents, but never explains what 'symbol' is or how it relates to the instrument (e.g. required for scoping, must match the instrument's issuer).

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 resource (one credit instrument) and the exact payload (full field evidence plus superseded amendment history), which separates it from credit.documents that only returns IDs. The retrieval verb is implied rather than stated, but the object and scope are 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?

Explicitly chains from the sibling: 'Use an instrument ID returned by credit.documents', telling the agent the prerequisite and the correct upstream call. It stops short of stating when NOT to use it or naming any other alternative, so it is clear context rather than full 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, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds genuinely new context beyond that: the result includes source evidence, and coverage is limited to the stored disclosure universe rather than all listed issuers. It still omits any note on result volume or pagination behavior.

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

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

Two tight sentences with no filler; the screening criteria are front-loaded and the scope caveat is placed as a closing qualifier. Every clause 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?

With no output schema, the description usefully states that source evidence is returned, and the coverage caveat sets expectations. But the undocumented 'limit' parameter and absence of any indication of result shape or ordering leave gaps for a screening tool with zero schema coverage.

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

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

Schema description coverage is 0%, so the description must carry the burden. It does convey units for two parameters ('below a percentage threshold' for headroomBelow, 'inside a month horizon' for springingWithinMonths), which is valuable, but it never mentions the 'limit' parameter or any of the defaults and bounds (limit 1-500, headroomBelow -10000-10000).

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 (Find/screen) and two precise resources: disclosed covenant headroom below a threshold and conditional springing maturities within a horizon. It is clearly distinguishable from credit.documents and credit.instrument, though it does not name them explicitly, so sibling differentiation is implicit 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?

Usage is implied by the screening semantics, and the closing sentence gives a useful scope caveat ('stored disclosure universe, not all listed issuers') that functions as a partial when-not. However, there is no explicit guidance on when to choose this over credit.documents or credit.instrument, nor any prerequisites.

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, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds useful context about the return payload (findings, watch items, coverage, cited evidence) and the cache-first vs. refresh behavior, which goes beyond the annotations. 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 a single, well-structured sentence that front-loads the core purpose and lists the key outputs. Every phrase earns its place; there is no redundant information.

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

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

For a read-only diagnostic tool with no output schema, the description adequately communicates the type of data returned and the caching behavior. It does not explain the exact structure of findings or coverage, but given the tool's simple parameter set and annotations covering safety, the description is reasonably complete. Minor gaps exist around the meaning of 'coverage' and how the mode parameter affects freshness.

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

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

The schema provides descriptions for only the symbol parameter (50% coverage). The description mentions 'cached or refreshed' which implicitly maps to the mode parameter but does not explicitly explain it. The limit and exchange parameters remain undocumented in both the schema and description, leaving the agent to infer their purpose. Since the description adds some context for mode but not others, a 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 clearly states the tool retrieves a cached or refreshed multi-source equity diagnostic and lists the returned content (findings, watch items, coverage, cited evidence). It implies a comprehensive diagnostic distinct from sibling tools like market.quotes or company.profile, though it does not explicitly name an alternative.

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

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

No guidance is provided on when to use this tool versus siblings like market.quotes, company.profile, or company.financials. The description only mentions the caching mode but does not explain under what circumstances a user should choose this diagnostic over other market data 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new context beyond them: archive rows are reconstructed from archived pages and are never live observations, plus the free-tier result cap of three rows. These are real behavioral caveats an agent needs. It stops short of describing freshness or how the tier limit is surfaced in 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?

Three short sentences with zero filler, front-loaded with what the tool returns before the caveats. Every sentence carries distinct information (content, data provenance, tier gating); nothing repeats the title 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?

With no parameters and no output schema, the description must carry the full load, and it does describe the returned fields and the provenance/tier caveats. It is nearly complete, missing only freshness/latency expectations and any note on how 'evidence' rows relate to the rate rows.

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

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

The tool takes zero parameters, which is the baseline-4 case. The description does not need to compensate for any schema gaps, and the schema's empty properties object is consistent with the no-argument 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 states a specific resource and scope: published GPU rental rates in USD per GPU-hour, with hardware variants, pricing basis and dated changes. It is clear what the tool returns, but it never distinguishes itself from siblings gpu.changes and gpu.history, so an agent must guess which of the three to call.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of the obvious alternatives gpu.changes (what changed) or gpu.history (time series). The only routing signal is implicit in the word 'board'. The tier note ('Pro unlocks full coverage; free previews three rows') is an access constraint, not usage guidance.

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

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

Annotations already establish the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds real behavioral context on top: results carry provenance and primary evidence, and sparsity in the output is not proof of unavailability — a genuinely useful warning about data completeness.

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 dense sentences, front-loaded with the core operation and ending with the most actionable caveat. The phrasing is jargon-heavy ('aggregate membership changes') but nothing is redundant.

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 diff tool with no required parameters and no output schema, the description covers the nature of the output and a key caveat, but leaves both parameters and the shape/size of a 'change' row unexplained.

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

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

Schema description coverage is 0% for two parameters. Neither 'limit' (1-100, default 50) nor 'gpuModel' (a bare string with no description) is explained in the description, so the agent gets no help on what gpuModel matches or how limit affects the diff.

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 identifies a specific resource and operation: dated price, availability and membership changes computed between 'real GPU observations,' with provenance and evidence. An agent can tell it is a diff/delta tool rather than a snapshot, though it never names gpu.history or gpu.board to sharpen the distinction.

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

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

There is no when-to-use statement and no comparison against the obvious siblings gpu.history and gpu.board. The closing line ('A missing row does not prove unavailable capacity') is an interpretation caveat about the returned data, not guidance on selecting or invoking this tool.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive), so the description earns credit for going further: it discloses that only real dated observations are returned with no interpolation, that reference indices are anonymised third-party values without public source links, and critically that the free tier ignores requested dates and returns latest preview values. That tier behavior is a substantial disclosure not present in structured fields.

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

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

Four sentences, front-loaded with the data description and tier gating last, so the ordering is sensible. However sentences like 'Archived pages are reconstructed, official offer versions are published history, and Azure effective dates remain separate' are cryptic and pack several unrelated facts without clear payoff.

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 7 mostly-undocumented parameters, the description should carry more weight. It covers data provenance and access tiering well but omits return shape, default date-range behavior, and the meaning of the basis filter, leaving gaps an agent would need to guess at.

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% (just includeFractional), and the description does not compensate: it never explains the 'basis' enum values (list/spot/ask/reserved/reference), how from/to bound the results, or what limit defaults to. Only 'reference' is obliquely characterized; the other six parameters are left undocumented 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 states what is returned: 'Real dated GPU price observations with source and evidence URLs for provider rates,' which combined with the title identifies this as GPU rental price history. It is clear but does not differentiate from siblings like gpu.board or gpu.changes, and the core purpose is buried under provenance caveats.

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

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

There is no guidance on when to use this versus gpu.board, gpu.changes, or power.history. The only usage-adjacent statement is the tier note ('Pro unlocks history; free returns latest preview values regardless of requested dates'), which describes an access constraint rather than when to select this tool.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds real behavioral context beyond that: 'Missing history is never estimated' discloses a no-imputation data-quality guarantee, and the ticker:exchange note describes symbol handling. Rate limits and pagination behavior remain undisclosed.

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

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

Front-loads the returned data and is reasonably compact, but the unexplained 'Pro:' prefix and the dense run-on list of fields slightly obscure rather than sharpen the message.

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 field enumeration usefully substitutes for return-value documentation, and the symbol rule covers a key input. But the two pagination parameters go undocumented and there is no guidance on result shape or limits, leaving gaps for a multi-parameter read tool.

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

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

Schema description coverage is 0%, so the description must carry all three parameters. It addresses only symbol (omit for company board, ticker:exchange format); limit and offset are never mentioned, and their default/range 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?

The description names the resource (weekly company hiring) and enumerates the data facets it returns: role/seniority/location mix, remote share, surge/freeze signals, peers, retained posting evidence. This makes the tool's content clear, but it never differentiates itself from near-siblings like company.hiring or market.hiring_movers, so an agent cannot tell which to pick from the text alone.

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?

One conditional rule is given ('Omit symbol for the company board'), which is genuine usage guidance for the symbol parameter. However there is no statement of when to use this tool versus company.hiring or market.hiring_movers, leaving the selection decision 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, openWorld, idempotent, and non-destructive behavior. The description adds only the temporal 'current' scope and the listed return fields; it does not disclose pagination, default limit behavior, timezone, or sorting, so it adds solid but limited behavioral context beyond the annotations.

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

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

A single dense sentence that front-loads the action and resource and packs the output dimensions into a compact list. There is no filler, repetition, or structural 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 simple read-only list with one optional parameter, the description supplies the output field names and the 'current' scope, which is the core of what an agent needs. Without an output schema, a little more detail on ordering, timezone, or limit behavior would make it fully complete, but the gap is minor given the tool's simplicity.

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 single optional limit parameter is not mentioned in the description, and schema description coverage is 0%. However, the parameter is semantically self-evident from its name and constraints (default 40, max 100, min 1), so the schema carries enough meaning and the description adds no additional parameter insight.

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') and a clear resource ('current economic releases'), and it enumerates the meaningful output fields such as event date, time, country, impact, actual, forecast, and prior values. It is clearly a calendar tool, but it does not explicitly differentiate itself from siblings like macro.series or macro.yield_curve.

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 'current economic releases' implies this is for the economic calendar rather than historical series, and 'current' suggests a live or dynamic dataset. However, there is no explicit when-to-use guidance, no stated exclusions, and no mention of alternatives such as macro.series or macro.yield_curve.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint false, so no safety contradiction exists. The description adds that the tool returns 'recent observations and source metadata' and only supports terminal-supported series, but it does not explain behavior around limits, date ranges, or unsupported series.

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 focused sentence with useful examples and no filler. It is appropriately concise and front-loaded.

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

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

With four parameters, no output schema, and zero schema-level parameter descriptions, the tool description is too incomplete. An agent cannot determine how to use limit or date filters correctly, nor 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 0%, so the description carries the burden of explaining parameters. It only hints at seriesId through examples and mentions 'recent observations', but it does not document limit, startDate, endDate, or their behavior.

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

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

The description clearly states the verb ('get') and resource ('FRED series supported by the terminal'), and gives concrete examples like DGS10 and VIXCLS. It is likely distinguishable from macro.calendar and macro.yield_curve, but it does not explicitly differentiate itself from those 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 phrase 'recent observations and source metadata for a FRED series supported by the terminal' implies when to use the tool, and the examples suggest valid series identifiers. However, it does not state when not to use it or point to alternatives such as macro.yield_curve or market.history.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that results include the FRED observation date for each point, which is a useful behavioral detail about the data source. However, it does not disclose how the limit parameter affects results, whether pagination exists, or the exact return shape. Since annotations carry the safety burden, this is acceptable but not enriched.

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

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

The description is a single, concise sentence that front-loads the core action and resource. Every word contributes meaning, and there is no redundant or filler text. It is appropriate for a simple tool with one optional parameter.

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

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

For a tool with one optional parameter and no output schema, the description explains what it retrieves (latest US Treasury yields by maturity) and adds a datum (FRED observation date). However, it omits any explanation of the limit parameter's effect, and since there is no output schema, it does not clarify the response structure (e.g., whether it returns an array of points). The gaps are minor for such a simple tool, but they leave room for agent confusion.

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

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

Schema description coverage is 0% and the description makes no mention of the only parameter 'limit'. The schema provides type, default, min, and max, but not meaning or purpose. An agent has no guidance on how limit influences the output (e.g., number of maturities returned). The description completely fails to compensate for the lack of schema documentation.

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

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

The description clearly states a specific action (get) on a defined resource (the US Treasury yield curve), and specifies the data quality (latest, by maturity, with FRED observation dates). It distinguishes itself from siblings like macro.series by focusing on the yield curve and mentioning the FRED data source. No ambiguity or tautology.

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

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

The description provides no guidance on when to use this tool versus alternatives such as macro.series or macro.calendar. It does not mention exclusions, prerequisites, or conditions that would route an agent away from this tool. The context of 'latest US Treasury yields' is implied but not explicitly contrasted with other macro 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?

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing key behavioral traits: the data is delayed, privacy-thresholded, sourced from opted-in users, and that missing buckets are suppressed/unobserved rather than zero. It also clarifies the unit is rounded researcher-hours, not people or recommendations, which prevents serious misinterpretation of the payload. This is exactly the kind of context the description should add.

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

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

Three sentences, front-loaded with the core concept, then the data coverage list, then critical caveats. The middle enumeration is somewhat list-like but each item maps to a distinct data domain, so it 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?

Strong on data semantics and caveats, but with no output schema and only 33% param coverage, the description leaves limit and window behavior undefined. For a parameterized retrieval tool it is adequate but has clear gaps an agent would want filled.

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 33% (only symbol documented) and the description adds no meaning for limit or window. The window enum (now/today/week) is self-documenting, but the limit parameter and how window interacts with the described 'delayed' data are unexplained, so the description fails to compensate for the coverage gap.

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

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

States the resource (research attention data from Gloom users) and enumerates the data domains covered: canonical listings, most researched tickers, abnormal attention, country/sector totals, price/volume context, news and history. Clear what it returns, though the verb is implicit and there's no explicit differentiation from sibling attention tools like apps.attention or social.ticker_posts.

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

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

No when-to-use or when-not-to-use guidance. It never mentions alternatives such as apps.attention or social.ticker_posts, so an agent has no signal for choosing between overlapping attention/stream tools. Usage must be inferred entirely.

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 readOnly/idempotent/openWorld/non-destructive, and the description adds genuine context beyond them: labeled type and impact opinions, revision provenance, primary-source links, disclosure of disabled/stale sources, and an explicit no-guessing policy for unlinked parties. It omits pagination and return-shape behavior, but the data-integrity disclosures are meaningful additions.

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 dense sentences with no filler, and the scope of coverage is front-loaded. However, the opening leads with data-quality attributes rather than the core purpose, slightly burying the lede.

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 15-parameter, no-required-arg tool with no output schema and 0% schema description coverage, the description should explain filtering, date semantics and pagination. It instead spends its budget on provenance claims, leaving the caller without enough to construct a correct query.

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

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

Schema description coverage is 0% across 15 parameters, so the burden falls entirely on the description, which explains none of them. The type enum values are echoed implicitly ('regulatory, clinical, legal, sanctions') and 'dated deadlines' hints at dateField, but from/to, symbol, agency, sector, source, status, limit, offset, changed and upcoming are all left undocumented.

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 conveys the domain (regulatory, clinical, legal, sanctions and trade events worldwide) but never states a clear verb or the scope relative to siblings like catalysts.event or catalysts.changes. It reads more as a data-quality manifesto than a statement of what the tool returns, so an agent can't cleanly separate it from its 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?

There is no when-to-use guidance, no mention of alternatives (catalysts.event, catalysts.changes, macro.calendar), and no indication of when a plain event lookup should be preferred over this calendar. Usage must be inferred entirely from the name.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and mutability. The description adds value by specifying that the data is dynamic ('30-day change', 'roles posted in the last 30 days') and that 'history exists' conditionally, which is useful context beyond the annotations.

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

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

The description is two sentences with no fluff. The first sentence front-loads key information about outputs and usage, and the second clarifies the purpose ('find who is hiring most or pulling back'). Every word earns its place.

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

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

With a single optional parameter, no output schema, and annotations covering safety, the description is largely complete. It covers what data is returned, the ranking basis, and the use case. One minor gap: it doesn't mention the default limit or whether pagination exists, but these are minor for this simple tool.

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

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

Schema description coverage is 0%, but the only parameter is 'limit', which is self-explanatory from the schema's name, default, and constraints. The description doesn't elaborate on it, but there's not much to add. The parameter's meaning (controlling number of results) is implicit, so a baseline of 3 is fair.

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 resource ('Companies under hiring coverage'), a clear action ('ranked by open roles'), and lists exact outputs ('30-day change', 'roles posted in the last 30 days', 'top function', 'top country'). It clearly differentiates from siblings like company.hiring (which likely focuses on a single company) by emphasizing a market-wide ranking perspective.

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

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

The description provides clear context: it's for finding who is hiring most or pulling back. It implies a market-level view, which distinguishes it from company.hiring. However, it doesn't explicitly state when not to use it or name alternatives, but for a simple, single-purpose tool this is acceptable.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a meaningful behavioral detail beyond annotations: 'Results retain the newest points when the byte cap requires truncation.' This discloses truncation behavior, which is non-obvious and important for an agent relying on data completeness. 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 truncation behavior is a single additional sentence that earns its place. No redundant phrasing 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 historical data tool with rich annotations (readOnly, idempotent, non-destructive), the description covers the essential behavioral caveat (truncation). The absence of an output schema means the agent doesn't know the exact return shape, but the description's mention of 'timestamped OHLCV' gives a reasonable expectation. It could mention pagination or date-range semantics, but the tool is simple enough that this is adequate.

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

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

Schema description coverage is only 33%, so the description carries some burden. The description mentions 'one symbol' and 'OHLCV price history', which adds meaning to the symbol parameter and the overall return type. However, it does not explain the semantics of limit, interval, startDate, endDate, or exchange beyond what the schema already provides. The schema covers symbol and exchange with descriptions, but the date range and interval parameters are left to their names and defaults. The description adds some value but does not fully compensate for the 67% coverage 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 states a specific verb ('Get'), a specific resource ('timestamped OHLCV price history'), and a scope ('for one symbol'). It clearly distinguishes this from sibling tools like market.quotes (current prices) and market.options_chain (options data). The mention of OHLCV and one-symbol scope makes the tool's purpose immediately identifiable.

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

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

The description implies usage context: it is for historical OHLCV data for a single symbol, which distinguishes it from market.quotes (current prices) and market.screener (multiple symbols). However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. The context is clear but the guidance is implied rather than 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?

Annotations already declare readOnlyHint/idempotentHint and destructiveHint=false; the description adds useful scope ('one underlying', 'optional expiration') and the returned fields. It does not disclose grouping, ordering, or pagination, but that is less critical given the read-only 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 single front-loaded sentence states the main action and the differentiating scope before adding the useful field list. There is no redundant wording or restatement of the tool name.

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 chain retrieval with no output schema, the description lists returned fields but not response shape or the meaning of `limit`. This is serviceable but leaves an agent to guess at a key optional parameter and the output structure.

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 50%; the description adds 'optional expiration' but says nothing about `limit` or `exchange`. In particular, `limit` is unexplained in both the schema and description, so an agent cannot tell whether it caps expirations, contracts, or something else.

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 ('Get') and resource ('calls and puts for one underlying'), and it names the returned data fields. This clearly distinguishes the options-chain tool from siblings like market.options_flow and market.quotes without needing to open 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?

The opening 'Get calls and puts for one underlying and optional expiration' states a clear use case: retrieve an options chain for a single symbol, optionally filtered by expiration. It does not explicitly name alternatives or exclusions, so it doesn't reach 5.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds substantive context beyond that: the $50K+ 'unusual' threshold, the dual live-vs-recorded mode switch, and the returned fields. 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, both earning their place: the first defines the resource and return fields, the second clarifies the mode behavior. The core purpose is front-loaded with zero filler.

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

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

With no output schema, the description compensates by listing return fields (contract, side, size, day volume, open interest, timestamp). Modes and filter effects are covered. Minor gaps: limit's effect on print count and any ordering/pagination behavior are not described.

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 covers days, symbol, and minPremium (75% coverage); limit has no schema description. The description adds meaning by tying filters to behavior — any of symbol/days/minPremium flips the query from live tape to historical search — and anchors minPremium to the $50K+ unusual threshold. Limit semantics remain unaddressed 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 states a specific verb ('Get') and a well-defined resource: large options prints (sweeps, blocks, $50K+ premium) with the returned fields enumerated. This is clearly distinct from sibling market.options_chain, which would return the full chain rather than unusual flow.

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?

Explains the two operating modes concretely: no filters returns the live tape, while a symbol, a day window, or a premium floor triggers a search of recorded prints. It doesn't explicitly name alternatives or exclusions, but the filter-vs-no-filter guidance is actionable for an agent deciding how to call it.

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive). The description adds real behavioral context beyond them: quotes may be delayed unless the caller is entitled to realtime, and a source timestamp accompanies the data so freshness is verifiable. Rate limits and failure behavior are not addressed.

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

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

A single front-loaded sentence with no filler; the entitlement caveat and returned fields are packed in without redundancy. Every clause earns its place, especially the field enumeration that compensates for the absent output schema.

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

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

With no output schema, the description correctly enumerates the returned fields and flags the delayed-vs-realtime entitlement dependency, which an agent needs to set expectations. Minor gaps remain: no mention of the 20-item cap behavior or what a missing symbol yields, but the essentials are present.

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

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

Schema description coverage is 67% and all three parameters carry their own schema descriptions, so the schema does the heavy lifting. The description reinforces the 'exact symbol' semantics of the symbols array but adds no format or batching detail beyond the schema's pattern, maxItems, and limit bounds. 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 gives a concrete verb (get) and resource (quotes) and specifies the payload (price, session move, volume, market state, source timestamp), so the agent knows exactly what comes back. It does not explicitly differentiate itself from neighbors like market.history or market.search, though 'exact symbols' hints at the distinction.

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 'one or more exact symbols' implicitly tells the agent this is a lookup by known symbol rather than a discovery/search tool, which is useful implied guidance. However, it never states when to use this versus market.search or market.history, nor any prerequisites for entitled realtime access, leaving 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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds minor context (US stocks, current data, ranking) but does not disclose behavior such as pagination limits or that the list is a snapshot. Given the annotations, 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 a single, tight sentence that leads with the action and resource, lists the categories, and includes the ranking qualifier. There is no redundancy or filler, making it highly concise and well-structured.

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

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

For a simple tool with only two parameters and no output schema, the description covers the core purpose and scope (US stocks, current movers, three categories). It does not describe the return format or any pagination behavior, but given the tool's simplicity and the schema covering parameter constraints, it is largely complete. Minor gaps like limit effect could be added but are not critical.

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

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

Schema description coverage is 0%, so the description must carry the burden. It does explain the category parameter by enumerating 'gainers, losers, or most active', mapping to the enum. However, the 'limit' parameter is not mentioned, and its default/max are only in the schema. The description partially compensates but leaves the limit behavior undocumented.

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 specific verb 'List' and resource 'current US stock gainers, losers, or most active names', and adds 'ranked by the market-data service' to clarify the output ordering. This distinguishes it from sibling tools like market.history (historical data) and market.quotes (quotes) without ambiguity.

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

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

The description provides no explicit guidance on when to use this tool versus alternatives such as market.history, market.quotes, or market.search. While the purpose is clear, there is no statement of exclusions or conditions for selecting this tool over siblings, leaving the agent to infer usage context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about searching by name or symbol and the disambiguation use case, but does not disclose additional behavioral details such as result shape or match semantics. 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 no filler. The core action is front-loaded, and the usage guidance is delivered economically in the second sentence. 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 two-parameter search tool, the description is largely sufficient: it defines what is searched, when to use it, and the schema covers constraints. The main gap is the lack of any detail about the returned instrument fields, especially since there is no output schema, but this is minor for the tool's stated purpose.

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

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

Schema description coverage is 0%, so the description must compensate. It partially does by explaining that the query parameter accepts a company name or symbol. However, it does not clarify the limit parameter's behavior or result shape beyond what the schema's default/constraints already convey, leaving a partial gap.

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

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

States a specific action ('Find tradable instruments by company name or symbol') and a clear resource. The second sentence, 'Use this before another market tool when a ticker is ambiguous,' positions it against sibling market tools, so an agent can distinguish it from tools like market.quotes or market.history.

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 context: use this when a ticker is ambiguous and before another market tool. This is strong guidance, though it does not name a specific sibling alternative or state explicit exclusions, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds specific return fields and the source (FINRA consolidated), providing useful context beyond the annotations without contradicting 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 a single sentence that front-loads the tool's purpose and lists key output fields without fluff. It is concise and well-structured, with no wasted words.

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

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

While the tool's purpose and output fields are clear, the missing explanations for 'limit' and 'years' parameters create a gap. With no output schema, the description's field list helps, but an agent would not know how to set sensible values for limit and years without external knowledge.

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% (only symbol has a description). The description does not explain 'limit' or 'years' parameters, leaving their meaning ambiguous. Since coverage is low, the description should compensate, but it does not mention these parameters at all.

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 ('Get'), a precise resource ('FINRA consolidated short-interest settlements'), and enumerates the returned fields (shares short, prior position, average volume, days to cover, change, revisions). This makes it distinct from siblings like market.quotes or market.history, which serve different data needs.

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

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

The description implies the tool is for short-interest data but does not explicitly state when to use it over alternatives or provide exclusions. It lacks explicit routing guidance such as 'use for short interest only' or 'not for real-time quotes', leaving usage context implicit.

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, openWorld and non-destructive, so the safety profile is covered. The description adds value beyond that by disclosing return shape ('publication and ingestion timestamps plus source links'), which matters since there is no output schema. It does not mention pagination or rate limits, keeping it short of a 5.

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

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

Three sentences, front-loaded with the core action before the filter and code details. Every sentence contributes; only the somewhat long topics enumeration risks being a run-on.

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, zero-required-param tool with no output schema, the description covers the topic code vocabulary and the returned fields well enough to call it correctly. The main remaining gap is the meaning/defaults of limit and the feed enum, which it never touches.

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

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

Schema coverage is 0%, so the description must carry the param burden. It does map 'text, tickers, topics, feed' to the corresponding parameters and, importantly, decodes the opaque topics vocabulary (mna, cb, energy, reg, crypto, earn, ipo, or category id) that the schema cannot express. It leaves limit and the feed enum values ('latest/top/breaking') unexplained, so compensation is partial.

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

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

States a specific verb+resource: 'Search or list market-news stories', with the filterable dimensions enumerated. It is clearly a news-retrieval tool, but it never positions itself against siblings like social.search_posts or market.search, which also return text content.

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

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

Usage is implied by the enumeration of filters, so an agent can infer 'use this to pull news by feed/text/ticker/topic'. However, there is no explicit when-to-use, no exclusions, and no routing to alternatives despite several search-like 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 cover readOnly/idempotent/non-destructive, so 'Read-only' is largely redundant. What earns credit is the concurrency disclosure: the returned revision is the one notes.save checks expectedRevision against, which tells the agent this is the correct pre-write read. It does not state behavior when the id is unknown.

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

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

A single sentence, front-loaded with the read-only qualifier and the scope. The trailing clause about expectedRevision is awkwardly worded but carries real information, so 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 correctly states what comes back ('the full content of one note'), which is the key return-value disclosure. Missing only error/not-found semantics for a simple one-parameter read tool.

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

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

One parameter with 0% schema description coverage, so the description carries the burden; it says the note is fetched 'by id', confirming the parameter is a note identifier. That is the minimum needed but adds no format, length, or lookup-failure 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?

States a specific verb (read) and resource (one note by id) and even ties itself to the sibling notes.save via the expectedRevision link, which helps an agent distinguish a single-note fetch from notes.list. It stops short of naming notes.list as the alternative, so differentiation is implied rather than explicit.

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

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

Usage is only implied: 'one note by id' signals a fetch-by-identifier tool, and the mention of notes.save hints at the read-before-write workflow. There is no explicit when-to-use/when-not statement or reference to notes.list for listing.

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, so safety is covered; the description's real added value is disclosing the returned metadata fields, which matters because no output schema exists. It correctly defers content retrieval to notes.get.

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

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

Two tight sentences; the read-only framing and return-field list are front-loaded, and the notes.get routing closes it with no wasted words.

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

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

No output schema, but the description enumerates the returned fields and points to notes.get for content, and annotations cover the safety profile. Adequate for a simple read-only list; limit/teamId behavior is the only minor gap.

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%, so the schema documents kind and scope well. The description echoes the account-vs-team distinction (scope) but adds nothing about limit or teamId, leaving marginal added value over the schema.

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

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

States a specific verb+resource (list notes) plus the scope (key owner's account or team) and even enumerates the returned fields, clearly distinguishing itself from notes.get which supplies content. An agent can tell exactly what it gets and what it doesn't.

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

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

Explicitly routes to the sibling notes.get for content, which is the key selection cue. It doesn't state when not to use notes.list versus notes.save, but the read-only framing and content routing give 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?

Annotations already declare destructiveHint=true and idempotentHint=true, and the description adds the crucial specifics: what is destroyed (the title and full content of the existing note), that matching is by kind+key, and the optimistic-concurrency guard via expectedRevision. It does not mention permission/membership requirements for team scope or the size limits the schema enforces.

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 dense sentences with zero filler, front-loading the write/upsert behavior before the concurrency and content-format details. Every clause carries distinct information an agent needs.

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

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

For a 7-parameter, no-output-schema mutation tool, the description covers the critical unknowns: upsert semantics, destruction scope, concurrency protection, and content format. It could go one step further by noting what is returned (e.g. a new revision to feed back into expectedRevision) or team-scope permission requirements.

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%: key, kind, scope and teamId are documented in the schema, while title and expectedRevision are not. The description compensates by explaining expectedRevision's semantics (value from notes.get, failure on stale revision) and content's format ('full note body in Markdown'), which the schema leaves bare — meaningfully more than the baseline for partial 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 ('Writes a note') and goes further to define the exact semantics: it either creates the note or replaces the title and full content of the existing note with the same kind and key. This upsert behavior is unambiguous and lets an agent distinguish it from siblings notes.get and notes.list 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?

Names notes.get as the source of expectedRevision and states the condition under which it should be supplied ('the call fails instead of overwriting a newer edit'), which is real when-to-use guidance. It does not spell out when to avoid this tool or explicitly frame the read-then-write workflow, so it stops short of full 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 the safe read-only/idempotent profile, so the description is free to add behavior it alone can convey. It does: rates are expressed as fractions, source URLs and quality flags are retained, and it explicitly excludes trading. That is genuine added context, though pagination/limit behavior and freshness are unstated.

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

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

One front-loaded sentence listing the scope, followed by two short qualifiers on units and provenance. Dense but every clause carries information; only the "No trading" tail is redundant with the 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-only board with no output schema, the description does reasonably well at conveying what comes back. It falls short on how the four filters behave, what the default limit means, and how results are ordered relative to perps.rankings.

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

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

Schema description coverage is 0% across 4 parameters, so the description carries the full burden and largely fails it. Mentions of "HIP-3 equities" and "dated underlying references" loosely gesture at the assetClass enum and underlyingSymbol, but limit and baseAsset get nothing and no filter semantics are explained.

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 (Read) and resource (cloud perpetual markets) and enumerates the returned fields: funding interval/raw/8h/simple APR, OI, premium, dated underlying references. Clear on its own, but it never distinguishes itself from the closely named siblings perps.rankings, perps.compare, perps.history, or power.board.

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

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

"No trading" is the only usage boundary, and it is redundant given readOnlyHint=true. There is no guidance on when to pick this board over perps.rankings or perps.compare, nor any note on how the filters should be combined.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive). The description adds genuine behavioral context beyond them: preserving native quote/collateral currency, contract type, and the normalization rule (mark / priceMultiplier) plus a warning not to conflate current and last-paid funding. That is real interpretation guidance an agent would otherwise lack.

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 dense sentences, front-loaded with the core purpose and followed by the normalization caveat. Each clause earns its place; 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 and no param descriptions, the description carries extraneous burden but delivers the data-shape guidance the agent needs to interpret the comparison. It still omits pagination/limit behavior, leaving a modest gap for a two-param 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 0% and there are two parameters. baseAsset is only obliquely implied by 'one canonical base asset', and the limit parameter (default 30, max 100) is never mentioned. The description does not compensate for the coverage gap.

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

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

States a specific verb (compare) and a precise resource scope: enabled venue contracts for one canonical base asset. It is distinguishable from perps.board/rankings by the 'compare across venues for a single base asset' framing, though it does not name those siblings directly.

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 'one canonical base asset' scope implies when to reach for this versus broader perps tools, and the funding caveat implies how to interpret results. But there is no explicit when-to-use/when-not or alternative routing despite four sibling perps 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 establish the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds real behavioral value beyond that: it warns that OI only exists from collection start and that historical funding does not imply historical OI, and notes the response carries observation boundaries and sample counts.

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 dense sentences with no filler, and the most important content caveat (OI/funding mismatch) is front-loaded. Structure is efficient for the amount of information conveyed.

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 gives useful return-shape hints but a five-parameter, zero-schema-coverage tool with no output schema needs parameter semantics that are absent. It is adequate on the data caveats but incomplete on how to drive the 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 0% and the description names none of the five parameters. 'Hourly candles' loosely gestures at resolution and 'observation boundaries' at from/to, but from, to, limit, marketId, and resolution are never explained, so the description fails to compensate for the documentation 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 names specific resources (OI/funding/premium observations, venue funding settlements, hourly candles), making the returned content clear. It does not, however, distinguish this retrieval tool from siblings like perps.board or perps.compare, leaving the agent to infer the boundary from name alone.

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

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

There is no explicit when-to-use guidance and no mention of alternative tools. The caveats about OI collection start hint at data availability but do not tell the agent when this tool is the right choice versus perps.board or perps.rankings.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description usefully adds the exclusion filter (stale, delisted, <$100K OI) but discloses nothing about ordering, result count, or how the rankings are sorted.

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

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

Two tightly written sentences with the content categories front-loaded and the exclusion scope trailing. No filler; every clause carries information.

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

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

For a zero-parameter ranking tool there is no input to document, and the description states both what is included and excluded. The gap is the absent output schema combined with no description of the return format or ordering, but the input side is complete.

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

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

The tool has zero parameters and a full-coverage (vacuous) schema, so there is nothing for the description to clarify. Baseline 4 applies.

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

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

The description names the specific ranked content — funding extremes, 24h OI surges, oracle dislocations, and closed-market equity premiums — so an agent knows this is a perp-metrics ranking list. It stops short of differentiating itself from siblings like perps.board or perps.compare, leaving overlap ambiguous.

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

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

There is no explicit when-to-use guidance and no named alternative, despite three closely related siblings (perps.board, perps.compare, perps.history). The only routing signal is the exclusion clause, which filters results rather than telling the agent when to pick this tool.

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

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

Annotations already carry the safety profile (readOnly, idempotent, non-destructive, open-world). The description adds real value beyond them: the data source (brokers connected in Gloom), the exact fields returned, and the important constraint that money is expressed in the account currency.

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

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

A single front-loaded sentence that leads with the access mode and then the resource and payload. It is dense but every clause (scope, fields, currency) earns its place, with 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 and no parameters, the description carries the return-value burden and does so by enumerating the account fields and noting the currency basis. It is complete enough to call correctly, missing only minor details like ordering or pagination.

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

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

The tool takes zero parameters, so the baseline is 4. There are no arguments whose semantics could be clarified, and the schema correctly forbids additional properties.

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

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

States a specific verb and resource: it returns every brokerage account the user connected, enumerating the fields (net liquidation, cash, buying power, margin, P&L). The purpose is unambiguous, though it never explicitly distinguishes itself from sibling portfolio.positions or portfolio.performance.

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

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

The description gives no when-to-use guidance and no exclusions. It implies a read-only listing but never routes the agent between this tool and its portfolio siblings, leaving selection 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 read-only, idempotent, non-destructive behavior, but the description adds substantial non-obvious context: the return contents (ranges by operating denominator and period, evidence paths, concentrations, unknowns) and the important caveat that chained percentages and shock impacts are estimates, never stock-return predictions. The requirement that custom transmission assumptions be explicit is a genuinely useful 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?

Four sentences, each carrying distinct weight, with the core action front-loaded before outputs, caveats, and tier limits. Dense but not padded; minor cost is that the tier and caveat sentences compete for attention.

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

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

With no output schema, the description covers return values well and discloses the estimate-vs-prediction caveat and tier caps. It is thin on the heavily nested scenario/transmission structure, so the schema's deepest inputs still require inference, but the practical calling picture is largely complete.

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

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

Schema description coverage is 0% for a 4-parameter tool with deeply nested objects, so the description must compensate. It explains that weights are signed NAV fractions and that depth maps to hops, but says nothing about cashWeight, the changeBps vs changePct distinction, or the transmission object's basis/factor/exposurePct fields, all of which are undocumented elsewhere.

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 ('Apply ... shocks') and resource ('weighted holdings'), and enumerates the shock dimensions (country, commodity, rates, FX, tariff, supplier, customer) that distinguish it from portfolio.positions and portfolio.performance. An agent can identify the operation without opening the schema.

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

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

Gives concrete context on tier limits — free preview handles one holding at depth one, Pro supports 100 holdings and four hops — which tells the agent when this tool is viable. It stops short of naming alternative tools or stating when not to use it, so it lacks explicit sibling routing.

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