Gloom

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

Annotations already cover read-only, destructive, and idempotent hints. The description adds valuable behavioral context beyond annotations: it clarifies that quantity applies only to portfolios and that the note is a label, not research. It also implies an upsert behavior ('Add or update'), which is consistent with idempotentHint=true. No contradictions found.

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

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

The description is three short sentences with no filler. Each sentence adds value: the action, the quantity constraint, and the note clarification. It is front-loaded with the core action and immediately provides the most important usage nuances.

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 mutation tool with annotations covering idempotency and safety, the description covers the essential usage context: what it does, key parameter nuances, and the upsert behavior. It does not mention return values, but the absence of an output schema makes that less critical. Overall, an agent can correctly invoke this tool based on the provided information.

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

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

Schema description coverage is only 17% (only teamId has a description). The description partially compensates by explaining the semantics of quantity and note, but it does not clarify symbol, exchange, or collectionId beyond their obvious names. Given the low schema coverage, more param clarification would be helpful, but the existing clarifications are useful.

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

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

Description clearly states the action: 'Add or update one item in a team collection.' This identifies the verb (add/update), the resource (team collection), and differentiates from sibling tools like collections.remove_symbol. The title and description align, and the note about quantity applying only to portfolios further clarifies scope.

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

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

The description gives clear context on when to use the tool (adding or updating a symbol in a collection) and clarifies specific usage nuances (quantity only for portfolios, note is a short label). It does not explicitly mention alternatives like remove_symbol for the opposite operation, but the purpose is unambiguous enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description carries little burden for safety disclosure. It adds useful context about the response fields (symbol, exchange, quantity, note), which helps the agent know what to expect. However, it does not disclose any behavioral traits like pagination, ordering, or rate limits, which could be relevant for a list-style read.

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

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

The description is a single concise sentence that front-loads the core output content. It avoids unnecessary words and is easy to parse. It could be slightly more informative, but it is appropriately sized for the tool's simplicity.

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

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

Given the absence of an output schema, the description does explain the return fields, which is helpful. However, it lacks guidance on how to specify the collection or team, does not mention pagination or limits, and does not differentiate from sibling tools like collections.list. For a read operation with annotations covering safety, this is adequate but not 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 only 33% (teamId has a description, collectionId and limit do not). The description does not compensate for this gap. It mentions 'one team collection' which hints at the teamId parameter, but it does not explain what collectionId refers to or how to obtain it, nor does it clarify the limit parameter. The schema already covers teamId, so the description adds minimal value beyond that.

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

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

The description states what the tool returns ('Items in one team collection: symbol, exchange, quantity for portfolios, and the note on each item') and the title clarifies it reads a watchlist or portfolio. It clearly identifies the resource (collection items) and implies a read operation, but it does not explicitly use a verb like 'gets' or 'retrieves'. It is distinct from siblings like collections.list (which lists collections) because it specifies item-level fields, though it doesn't explicitly name the sibling.

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

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention when to use collections.get over collections.list or collections.add_symbol, nor does it state any prerequisites or context (e.g., having a collectionId from collections.list). The title implies a read operation, but there is no explicit usage context or exclusions.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds non-obvious behavior: omitting teamId expands the result across all teams the key can reach, which is not evident from the schema alone. There is 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 that front-loads the action and resource, then packs the key scoping behavior efficiently. Every part of the sentence earns its place 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?

For a read-only list tool with no required parameters and a simple schema, the description covers the main scoping behavior and cross-team semantics. It does not describe the return shape or whether limit applies per team, but the annotations carry the safety profile and the schema constrains limit. This is adequate 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?

The description adds useful meaning for teamId by explaining the omission behavior, complementing the schema's teamId description. However, limit is not semantically explained in the description, and the schema only provides numeric constraints. With 50% schema description coverage, the description only partially compensates.

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 lists watchlists and paper portfolios, with an explicit scope: one team or all teams the key can reach. This distinguishes it from mutation siblings like collections.add_symbol and collections.remove_symbol, though it does not explicitly name an alternative list tool.

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

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

The description provides conditional guidance for the teamId parameter, explaining that omitting it reaches every team the key can access. However, it does not state when to prefer this tool over alternatives such as collections.get, notes.list, or teams.list, and offers no exclusions.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the safety profile is covered. The description adds minimal behavioral context ('Remove one item'), which is consistent with the annotations. It doesn't add details about side effects, permissions, or error handling, but given the annotation coverage, the description is acceptable and doesn't contradict 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 concise sentence with no fluff, which is appropriately short. However, it is so minimal that it sacrifices informativeness for brevity. It front-loads the action but doesn't provide enough substance to be fully useful.

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 4 parameters (2 required) and no output schema, the description is quite incomplete. It doesn't mention return values, error scenarios, or additional context like how to get collectionId or when exchange is needed. The annotations cover safety, but the description leaves many operational details unaddressed.

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

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

Schema description coverage is only 25% (only teamId has a description). The tool description does not explain any parameters, such as what collectionId refers to, the format of symbol, or the optionality of exchange. With low schema coverage, the description should compensate, but it doesn't, leaving agents to infer parameter meaning from names and context.

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

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

The description states a specific verb ('Remove') and a resource ('one item from a team collection'), which is clear and distinct from the sibling 'collections.add_symbol'. However, it doesn't explicitly mention 'symbol' or 'watchlist/portfolio' as in the title, so it's not fully precise, but the tool name and title provide the missing context. It adequately conveys the core action.

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

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

There is no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when removal is appropriate, or contrast with 'collections.add_symbol' or other collection operations. An agent must infer usage solely from the name and title.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the detail about returning source dates for events, which is useful but does not disclose other behaviors like result limits, pagination, or handling of missing data. Given the strong annotation coverage, the description provides only modest added value.

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, efficient sentence that front-loads the action and key details. It has zero waste and is immediately understandable, which is ideal for an AI agent scanning multiple tool definitions.

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 annotations covering safety, the description is nearly complete. It states what events are returned and the scope (one company). The lack of an output schema is acceptable for a straightforward getter. Minor gaps like pagination or time-range behavior are not critical given the tool's simplicity and 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% (symbol and exchange are described; limit is not). The description does not explain any parameters beyond what the schema already provides. The limit parameter is self-explanatory with its default and bounds. The description adds no parameter-specific detail, so it relies on the schema, which is adequate but not enhanced.

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

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

The description clearly states the tool's function: retrieving dividends, stock splits, and earnings events for a single company, including each event's source date. This distinguishes it from siblings like company.financials or company.profile, which cover different data. The verb 'Get' and specific event types make 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 provides clear context by specifying 'for one company,' implying it is not for multi-company queries. However, it does not explicitly name alternatives or state when not to use it. Since the purpose is distinct among siblings, the context alone is sufficient, but it lacks explicit exclusionary 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 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 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 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 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 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 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?

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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat safety. It adds 'delayed or entitled realtime' which hints at entitlement/permission requirements, but does not explain rate limits, symbol-not-found behavior, or authentication nuances. 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?

A single, focused sentence that front-loads the purpose and lists the return fields. No wasted words; every clause adds 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?

The description is reasonably complete for a read-only quote tool: it names the key fields returned and implies exact-symbol usage. However, it omits details about limit behavior, multi-symbol handling, and error cases (e.g., invalid symbol). Given no output schema and moderate complexity, it could be more thorough.

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 'symbols' has a description; 'limit' and 'exchange' have none). The tool description adds no information about these parameters, such as what 'limit' controls or how 'exchange' disambiguates symbols. Since coverage is low, the description must compensate, but it does not.

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 the resource 'market quotes', and lists the specific data fields returned (price, session move, volume, market state, source timestamp). It is distinct from siblings like market.history or market.search, but it does not explicitly name alternatives or exclusions, so it misses the top score.

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 mentions 'exact symbols' but provides no explicit guidance on when to use this tool versus market.search (for symbol discovery) or market.history (for historical data). There is no when-not-to-use or alternative routing, so the agent must infer usage context from the resource 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 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 communicate read-only, idempotent, non-destructive behavior, so the description is not burdened with safety disclosure. It adds value by telling the agent that every story includes publication/ingestion timestamps and source links, which sets expectations for 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 tight sentences, each earning its place: the first states the operation, the second adds filter capabilities and output expectations. No redundant phrasing or boilerplate.

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

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

Given the read-only annotation and a simple list/search tool, the description covers the essential output fields and filter dimensions. It does not describe result ordering, pagination, or how arguments combine, but the low operational risk and schema constraints keep this from being a major 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 description coverage is 0%, so the description must compensate; it does map most parameters to filter categories (feed, text/tickers/topics) but leaves limit and the precise semantics of combining filters undocumented. The input schema's property names and constraints do most of the work.

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

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

The description opens with a clear action-resource pair: 'Search or list market-news stories,' and then enumerates the supported filter dimensions (feed, text, tickers, topics). This makes it easy to distinguish news.stories from sibling market tools such as market.search or market.history, which operate on quotes and historical data.

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 does not state when to prefer this tool over alternatives or when not to use it. There is no mention of queries better suited to market.search, company.analyst_research, or macro.calendar, and no prerequisites or exclusions are provided.

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, and non-destructive behavior. The description adds useful behavioral context by disclosing that the result includes a revision and that it is meant to feed into notes.save, which is beyond what the structured annotations provide.

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

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

A single efficient sentence that front-loads the operation and object, with no filler. Every word contributes meaning, including the revision-for-save workflow detail.

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 full annotation coverage and one self-explanatory parameter, the description is complete. It states what is returned, the revision detail, and the intended downstream use, so an agent has enough to call it correctly.

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

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

The schema has no description for id (0% coverage), but the description's phrase 'by id' clarifies that id identifies the note to fetch. It does not add format or source details beyond the schema's string constraints, which is adequate for a single obvious parameter but not exceptional.

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

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

The description states a specific operation: retrieve the full content of one note by id. It is clearly distinguished from notes.list (listing) and notes.save (writing) by focusing on a single read with a revision payload.

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

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

The description clearly implies when to use this tool: when you need one note's content and its revision, especially before a notes.save call. It does not explicitly mention alternatives or exclusions, but the single-note-by-id scope makes the intended use unambiguous.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, so the description adds value by specifying the returned fields (id, kind, key, title, revision, last editor) and explicitly setting the boundary that content is not included here. This gives the agent useful behavioral expectations 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?

Two sentences with no wasted words: the first front-loads the return fields and scope, the second clarifies the boundary with notes.get. 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 read-only list tool with four optional parameters and no output schema, the description adequately covers what is returned and how it differs from fetching content. It relies on the schema for parameter details like limit and teamId, which is acceptable given the 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 75%, with meaningful descriptions for kind, scope, and teamId, and the limit parameter has default/min/max constraints. The description itself adds little parameter-specific meaning beyond mentioning the account/team distinction, so it does not significantly lift the schema's baseline.

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

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

The description clearly identifies the resource (notes) and the intended scope (key owner's account or team), and distinguishes this tool from notes.get by stating that content comes from notes.get. However, the verb 'list' is carried by the title and tool name rather than the description itself, which keeps it from a perfect 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 sentence 'Content comes from notes.get' gives a clear routing signal: use notes.list for summary metadata and notes.get for full content. It does not explicitly state exclusions or when to use notes.save instead, but the context is clear enough for an agent to select the right 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 mark idempotentHint=true and destructiveHint=false; the description adds genuinely useful behavior by explaining the upsert semantics ('create or replace'), the optimistic concurrency guard ('refuse overwriting a newer edit'), and that content is Markdown. No contradiction with annotations.

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

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

Three sentences each earn their place: the core action, the concurrency behavior, and the content format. It is front-loaded and free of filler.

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

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

For a 7-parameter write tool with no output schema, it covers the action, scoping, concurrency, and body format; the schema handles key, kind, scope, and teamId. It is complete enough for correct invocation, though a one-line note on what the call returns would have been helpful.

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 schema coverage at 57%, the description compensates for the two undocumented parameters: expectedRevision is tied to notes.get and overwrite protection, and content is defined as the full Markdown body. Only title lacks any explanation, but it is a minor optional metadata field.

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 'Create or replace a note,' specifying both the action and the resource, and scopes it to 'the key owner's account or in a team.' This clearly differentiates it from the read-only siblings notes.get and notes.list.

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 write usage by using 'create or replace' and tells the agent to source expectedRevision from notes.get, which is a concrete tie to an alternative. It does not explicitly state exclusions, but the write-vs-read split is clear enough given the sibling set.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds that the response includes specific fields and that it is for one exact ticker, which is useful context. However, it does not disclose pagination behavior (though limit/offset are in the schema), error handling for invalid tickers, or any rate limits. It adds some value but does not go beyond what the annotations and schema already convey.

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

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

The description is a single sentence of about 20 words, front-loaded with the action and resource, and efficiently lists the returned fields. There is no filler or redundancy; every word adds value.

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 operation with three parameters (one required), the description is largely complete. It states the scope (single ticker), the recency (recent), and the fields returned. It does not mention pagination explicitly, but that is captured by the schema defaults. Since there is no output schema, the description's field enumeration is helpful. Minor omissions like empty-result behavior are acceptable for this type of 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 ticker has a description). The description does not compensate for the undocumented limit and offset parameters. While those are standard pagination parameters, the description doesn't explain their semantics, defaults, or maximums. The phrase 'one exact ticker' reinforces the ticker schema description but adds little beyond it. Given the low coverage, the description should have clarified limit and offset but didn't.

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 ('List') on a specific resource ('SEC filings') with a specific scope ('one exact ticker') and enumerates the returned fields (filing date, acceptance timestamp, form, accession, source URLs). This distinguishes it from sibling tools like sec.thirteenf_holders or sec.insider_transactions, which target specific filing types.

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 ticker ('one exact ticker') and implies a time-bound set ('recent'), but it does not explicitly state when to prefer this over alternatives or when not to use it. There is no mention of exclusions, such as 'for 13F filings use sec.thirteenf_holders' or 'for broader market data use market.history.' The guidance is adequate but not 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, openWorldHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds context about the data source (Form 4 filings) and the specific output (purchases, sales, grants, dispositions with provenance), which goes 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, efficient sentence that front-loads the core action ('Read recent Form 4 filings for one ticker') and includes all necessary details without any fluff.

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

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

The description gives a solid overview of what the tool returns, but it does not explain the behavior of the limit parameter, pagination, or response structure. Given that there is no output schema, these gaps leave the agent somewhat under-informed, though the tool is simple enough that a basic call could still succeed.

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 does not mention parameters at all. Schema coverage is only 50% because limit has no description. The description fails to compensate for the missing limit explanation, leaving the agent to infer its purpose (e.g., max number of filings returned).

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'), resource ('Form 4 filings for one ticker'), and what it returns (insider purchases, sales, grants, dispositions with provenance). This clearly distinguishes it from sibling tools like sec.filings (general filings) and congress trades, making its 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 implicitly communicates usage by specifying 'for one ticker', which tells the agent this is a single-symbol insider transaction tool. It does not explicitly mention alternatives or exclusions, but the context is clear enough that an agent would know to select it for insider transaction queries.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds behavioral context by stating it compares the latest and prior quarter and enumerates the output types (positions, exits, weight changes, counts). This goes beyond simple repetition of annotations and gives the agent a clear expectation of the result nature.

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

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

The description is a single, dense sentence with no filler. It front-loads the core purpose ('Compare the latest and prior quarter') and packs in the key details without redundancy. Every part of the sentence contributes 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?

The description gives a solid overview of the output but omits parameter explanations and does not specify the exact response structure (no output schema provided). Given the tool has four parameters with zero schema descriptions, the description is not fully sufficient for an agent to call it correctly without additional schema inspection. It covers the 'what' but not the 'how' or 'format'.

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 by explaining parameters. It only hints at 'funds' via 'up to 50 funds' and 'ranked by the provider' implies the 'rank' parameter, but it does not explain 'limit' or the 'quarter' format (e.g., YYYYQ#). The description adds minimal value for parameter understanding, leaving agents to infer from defaults and enums.

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 'Compare', the resource '13F crowding', and the scope 'across up to 50 funds ranked by the provider', followed by specific outputs ('new positions, exits, aggregate weight changes and the fund count'). This distinguishes it from sibling tools like sec.thirteenf_holders, which focus on individual holdings rather than aggregate crowding.

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

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

The description implies when to use this tool (for comparing quarterly crowding changes) but does not explicitly mention alternative tools or conditions when not to use it. It lacks contrast with siblings such as sec.thirteenf_holders, so usage 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 indicate readOnly, idempotent, and non-destructive behavior. The description adds meaningful context by revealing response contents: previous-quarter exits, reported value, shares, fund weight, and action. It also clarifies that the quarter can be the latest one or a requested one.

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 then lists the most relevant output fields. 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 paginated lookup tool, the description covers the main input semantics and even hints at the output fields despite having no output schema. The main missing piece is explicit routing guidance against closely related 13F tools, but the description is otherwise sufficient 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?

With only 25% schema description coverage, the description partially compensates by clarifying the ticker scope and the 'latest or requested quarter' behavior. However, it does not explain the quarter format, the limit maximum of 25, or the offset pagination semantics beyond the word 'Page'.

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 ('Page') and a clear resource ('funds holding one ticker'), and it names the quarter scope. It is distinguishable from siblings like sec.filings or insider_transactions, though it does not explicitly contrast itself with sec.thirteenf_crowding or company.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?

There is no explicit guidance about when to use this tool versus alternatives such as sec.thirteenf_crowding or company.holders. The description only states what the tool does, not when it is the right choice or when another tool should be used instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, covering the safety profile. The description adds behavioral context beyond annotations by specifying that the output includes role and member count, and that the teams belong to the key owner. This scoping information is not present in annotations and adds value for the agent.

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 the core purpose front-loaded and no superfluous words. The first sentence states what it returns, and the second explains its downstream use. Every sentence earns its place, 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 one optional parameter and no output schema, the description is fairly complete. It explains the output fields (role, member count) and the practical use of the returned team IDs. It does not explicitly mention the limit parameter, but that is a minor omission given the schema already covers it. The absence of pagination details is acceptable for a simple list endpoint.

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. However, the only parameter, 'limit', is self-explanatory with its default (50) and max/min constraints already defined in the schema. The description does not mention pagination or limit behavior, but the schema provides enough information. Given the simplicity, a score of 3 is appropriate as the description does not add significant 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 clearly states the tool's purpose: listing teams that the key owner belongs to, including role and member count. It uses a specific verb-resource pair ('list teams') and adds useful context about how the output is used (team ids feed notes and collections tools). It distinguishes itself from siblings by focusing on the team listing aspect, which no other sibling provides.

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

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

The description explicitly mentions that team ids feed the notes and collections tools, providing a clear use case for when this tool should be invoked. It also implies that it is a precursor to those tools, and since there is no alternative team-listing tool among siblings, this guidance is sufficient and precise.

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