Stock Short Selling & Short Interest Data

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

No annotations, so the description carries the burden. It discloses ordering ('newest first') and adjustment ('adjusted'), which is real behavioral info. But it omits rate limits, page size defaults, permissions, and error behavior.

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

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

Single dense sentence, front-loaded with resource and ordering, then usage constraint. No filler or repetition.

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

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

Covers the core data shape and ordering, adequate for a simple read tool. Missing: whether symbol/isin are mutually exclusive or how to resolve conflicts, limit semantics, return structure details, and any failure modes.

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

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

Schema coverage 0%, so the description must compensate. It clarifies symbol/isin are alternatives ('OR'), which the schema does not state as a constraint. However, the limit parameter and its 1–400 range/default are not explained, and neither is the string format for symbol/isin.

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

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

States a specific verb+resource ('Daily closing prices of one company') with clear scope. Slight ambiguity from 'adjusted' and the parenthetical '(company page chart)', but the core purpose is unambiguous.

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

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

'Pass symbol OR isin' implies usage but is a data requirement, not when/when-not guidance. No explicit conditions for choosing this over a sibling — implied context only.

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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that results are 'published' short positions and describes the returned shape (current, historic, statistics timeseries), which is meaningful context. However, it does not mention rate limits, permissions, data freshness, or pagination behavior — gaps that matter for a data-retrieval tool with zero annotation coverage.

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

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

Two compact sentences, zero waste. The first front-loads what the tool returns and the second immediately clarifies the identifier options — ideal ordering for an agent scanning for the right tool.

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

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

For a two-parameter read tool with a fully documented schema, the description covers purpose, return shape, and identifier flexibility. It stops short of stating which sibling to prefer or any usage caveats, but no output schema exists and the essential calling information is present.

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

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

Schema coverage is 100%, so the schema already documents both parameters, including format hints like 12-character ISIN and case-insensitive US ticker. The description reinforces that either identifier may be passed but adds no format or constraint details beyond what the schema provides, so baseline 3 is appropriate.

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

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

States a specific verb+resource (get short positions of one company) and enumerates exactly what is returned: current positions per holder, historic positions, and statistics timeseries. This clearly distinguishes it from siblings like get_top_short_positions or get_trending_short_positions, which are aggregate/ranking tools rather than single-company detail.

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 says to 'Pass symbol OR isin', which implies it is a per-company lookup and that either identifier works, but it does not explicitly state when to use this tool versus single-company siblings such as get_shortseller_positions or search_companies. Usage is implied by the resource scope rather than stated as explicit when-to-use 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?

With no annotations, the description must carry the behavioral burden, and it usefully explains the sign convention for positionPctChange, which helps interpret results. However, it omits ordering, freshness window, pagination behavior beyond the schema's limit, and any confirmation that this is a read-only feed operation.

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 single sentence is front-loaded with the scope and resource, and the field interpretation follows efficiently. There is no filler, though the structure could be slightly clearer about what exactly is returned.

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, one-parameter list tool with no output schema, the description gives the core purpose and interprets one key field. It does not describe the returned entries' structure or sorting, which is a meaningful gap when no output schema exists, but the tool's complexity is low enough that the description is minimally serviceable.

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

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

Schema coverage is 100%, so the only parameter, limit, is already fully described in the schema. The description adds no parameter-level detail, making the baseline 3 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 identifies the resource (short position changes) and the scope (most recently published, feed page), which distinguishes it from siblings focused on top, trending, or company-specific short positions. The verb is only implicit in the tool name, but an agent can still tell what data this returns.

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

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

There is no explicit guidance on when to use this tool versus get_trending_short_positions, get_top_short_positions, or get_company_short_positions. The parenthetical '(feed page)' hints at a chronological context, but no conditions or exclusions are stated.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses scope (current positions) and sorting (largest position first), but omits whether the operation is read-only, how pagination or limits work, and what happens on invalid seller names.

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

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

A single sentence with no wasted words, front-loading the resource scope and then the ordering behavior. It is appropriately sized for a simple one-parameter read tool.

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

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

The tool is low-complexity and the single parameter is fully documented in the schema, but there is no output schema. The description does not explain the shape of returned position data or any pagination/limit behavior, leaving minor gaps for an agent calling it.

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

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

Schema description coverage is 100%, so the name parameter is already documented as a case-insensitive short seller/holder name. The description adds only the concept of 'one short seller' and does not extend syntax or usage beyond the schema, making 3 the appropriate 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 states a specific verb+resource: fetching all current short positions for one short seller, with ordering noted. It is clear enough to distinguish from get_company_short_positions by focusing on a short seller rather than a company, but it does not explicitly name or contrast with any sibling 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 gives no explicit when-to-use or when-not-to-use guidance. It implies usage for a specific short seller, but does not mention alternatives like get_top_short_positions or get_company_short_positions, nor any prerequisites 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?

With no annotations provided, the description carries the full behavioral burden, and it does communicate the data domain (cumulative net short positions). However, it says nothing about ordering, result limits, pagination, or rate limits, which an agent would want for a list endpoint.

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, front-loaded with the resource and followed by the region legend, with no filler. The parenthetical pack is dense but every clause conveys 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 single-parameter read tool with no annotations and no output schema, the description covers what data is returned and what the region values mean, which is the minimum viable. It omits ordering, count, and pagination details that would make the return predictable.

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, and it does by explaining what the EU/US enum values map to (European registers vs FINRA short interest). That is real added meaning beyond the bare enum, though no further syntax or default behavior is offered.

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 with the largest cumulative net short positions) and qualifies it as a home-page top list, so the agent knows what is being fetched. It does not explicitly distinguish itself from near-siblings such as get_trending_short_positions or get_recently_updated_positions, leaving ranking semantics to inference.

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

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

No statement of when to choose this over the other short-position tools; the 'home page top lists' hint implies a leaderboard use case but no alternative or exclusion is named. An agent must guess whether 'top' means ranking by size, net value, or something else relative to the sibling tools.

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

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

With no annotations, the description carries the full behavioral burden. It does disclose the ranking semantics (magnitude of net short position change, over 7D or 28D) and that both increase and decrease directions exist, which is useful. It says nothing about result size, ordering, pagination, or that this is a read-only listing, so significant gaps remain.

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 with the core ranking concept front-loaded and no filler. The trailing parenthetical '(home page trend lists)' is the only slightly noisy element, and it does convey source context.

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 3-required-param tool with no annotations and no output schema, the description covers the ranking concept and two of three parameters but omits region entirely and gives no sense of return shape or result limits. Adequate but with clear gaps.

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

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

Schema description coverage is only 33% (only direction is documented in-schema). The description maps the timeFrame enum to human terms ('7 or 28 days') and echoes direction ('increase or decrease'), adding real value for two of three params. The region parameter (EU/US) is never mentioned anywhere, so the description does not fully compensate for the coverage gap.

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

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

The description names a specific resource (companies' total net short position) and a specific ranking criterion (largest move over 7 or 28 days), which implicitly separates it from get_top_short_positions (largest position) and get_recently_updated_positions. It never explicitly names those siblings, so an agent still has to infer the boundary.

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

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

The parenthetical '(home page trend lists)' gives some usage context, implying this is the tool for trend/momentum views. There is no explicit when-to-use versus when-not-to-use guidance and no alternative tool is named, leaving the choice against the five sibling position tools to inference.

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

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

With no annotations, the description carries the full burden, and it does disclose the 5-match cap and the returned fields (name, symbol/isin, totalShortPct, website). It says nothing about permissions, error/empty-result behavior, or whether there is any way to page past the 5-match limit, which matters for a search tool agents may rely on for disambiguation.

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

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

Three short sentences: what it finds, what comes back including the cap, and what to do next. Zero filler and the actionable routing is front-and-center.

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

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

For a single-parameter lookup with no output schema, the description supplies the return shape and the match limit, which is exactly what is missing from structured fields. It could note behavior on zero matches or point to sibling alternatives when the entity is already known.

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

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

Schema coverage is 100% and the single parameter is self-documenting, so the baseline 3 applies. The description restates the accepted key types but adds no format guidance (e.g., ISIN casing rules) 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?

States a specific verb and resource ('Find companies with published short positions') and immediately scopes the lookup keys (name, ticker, ISIN). It also names the sibling it hands off to, so an agent can distinguish it from the other get_* retrieval tools.

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

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

Explicitly routes the agent forward: 'Pass the returned symbol or isin to get_company_short_positions.' That makes the search-then-fetch workflow clear. It stops short of stating when NOT to use this tool (e.g., when the symbol is already known), so 4 rather than 5.

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