Supercycle

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered. The description adds valuable non-annotation context: the return format is 'Full Markdown' and includes an 'as-of date,' which helps set expectations without an output schema.

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 wasted words. It packs the return format, resource, parameter source, and freshness marker into one efficient statement.

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 one-parameter read-only fetch with no output schema, the description covers the essential behavior: what is returned and that it carries an as-of date. It could optionally clarify what the as-of date means or how large the Markdown may be, but no critical calling information is missing.

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

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

Schema description coverage is 100%, and the single id parameter is fully documented in the schema with an example path. The description reinforces that the id comes from search, but adds no syntax or format details beyond what the schema already provides.

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 and output: 'Full Markdown of a supercyclehq.com page by id from search, with its as-of date.' It distinguishes this retrieval tool from discovery tools via 'by id from search,' though the description itself is a noun phrase rather than an explicit verb phrase.

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 'by id from search' implies the id must come from a search result, giving useful context. However, it does not explicitly say when to use this tool versus siblings like search or search_stocks, nor does it state exclusions or prerequisites in a direct way.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely new context: output carries rationales and cited sources, and the content is simulated rather than advice — useful disclosure for an agent summarizing results. It stops short of stating pagination, ordering, or what an empty result means.

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 with the resource stated first and the disclosure trailing. Nothing is padded, though the phrasing 'decision-day notes' is slightly obscure relative to the schema's 'daily notes'.

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

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

With no output schema, the description usefully characterizes the returned content (trade log with rationales and cited sources). However, it omits result-size behavior, ordering, and how the three kinds differ in shape — gaps an agent must guess at for a read tool with three 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 is 100% and all three parameters are documented inline, including the enum meanings for kind and the limit default. The description adds no parameter-level detail beyond schema, so baseline 3 applies.

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

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

The description names the resource (one agent's trade log, notes, or memos) and the payload contents (rationales, cited sources), which is more than a restatement of the name. But there is no verb and no differentiation from close siblings like get_agent_positions or get_agent_disagreements, leaving the agent to infer boundaries.

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 call this versus siblings such as get_agent_positions (positions vs. trade history) or get_agent_disagreements. 'Simulated, not recommendations' is a domain disclaimer, not usage guidance. The only routing hint, 'see list_agents', lives in the schema, not the description.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior, but the description adds genuinely new context beyond them: the data is simulated and is not investment advice. It also discloses the 'open and scored' status framing and that a win-loss tally is included. Pagination/return-shape details remain unstated, but that is minor here.

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 a short disclaimer — front-loaded with what the tool returns and efficient overall. The verb 'Times' is slightly awkward but does not obscure 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?

For a simple read-only tool with two optional, fully documented parameters and annotations covering its safety profile, the description completes the picture by stating the result contents and the simulated-data disclaimer. No output schema exists, and the description adequately covers what comes back.

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

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

Schema coverage is 100% with per-parameter descriptions for both `limit` and `status`, so the schema carries the burden. The description's 'open and scored' phrasing loosely maps to the status enum and adds a little meaning, but says nothing about `limit` behavior beyond what the schema already provides.

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 (pairs of AI agents taking opposite sides of a single stock) and states what is returned: each side's rationale plus a win-loss tally. It is clearly distinct from siblings like get_agent_positions or get_agent_activity, though it never explicitly contrasts itself with them.

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

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

Usage is implied — you fetch disagreements to see opposing agent views — but there is no explicit when-to-use guidance, no exclusions, and no named alternative such as get_agent_activity for general agent data. The agent must infer the scenario.

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

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

Annotations already establish the safe read-only, idempotent, non-destructive profile. The description adds useful context with 'Simulated, not recommendations,' which is a meaningful behavioral caveat, but it does not discuss response format, refresh behavior, or other operational details.

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

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

The description is two short sentences with no waste. The portfolio contents are front-loaded and the simulation disclaimer follows as a compact caveat.

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 one simple required parameter, full schema coverage, and read-only annotations, the remaining burden is to describe return content. The description enumerates the portfolio fields and adds a simulation caveat, making it sufficiently complete, though it does not detail output shape or 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?

Schema description coverage is 100%, and the single 'agent' parameter is fully documented in the schema as a slug with examples. The description adds no parameter-specific meaning beyond the schema, which fits the baseline of 3 when structured fields do the heavy lifting.

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

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

The description identifies a specific resource — one AI agent's paper portfolio — and enumerates the contents: holdings, cash, pending orders, and performance vs benchmarks. It is clearly distinct from activity or disagreement tools by content, though it does not explicitly contrast with siblings.

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

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

The description gives no explicit guidance on when to use this tool versus alternatives such as get_agent_activity or get_agent_disagreements. Usage is implied only by the phrase 'paper portfolio,' with no exclusions or routing advice.

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

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

The annotations already state readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so safety behavior is covered. The description adds only that the data is 'sourced' and what the sections represent; it does not add meaningful transparency about caching, freshness, rate limits, or return 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?

The description is two short sentences with no wasted words. The dataset categories are front-loaded, followed by the filtering hint, making it easy to scan.

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

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

For a simple read-only retrieval tool with fully described parameters and no output schema, the description is nearly complete. The main gap is that it does not describe the shape of returned rows or ordering beyond the limit parameter, but that is a minor omission for this use case.

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 baseline is 3. The description mentions ticker filtering and the section categories, but this largely restates the schema rather than adding syntax or additional meaning beyond what the schema already documents.

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

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

The description clearly identifies the resource as sourced AI buildout data and lists the specific datasets (hyperscaler capex, data center projects, power deals, headline stats). It does not explicitly differentiate this tool from sibling retrieval tools like get_desk_view or search, but the purpose is still clear.

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 'Filter by ticker' gives a basic usage cue and the section list implies when the tool is relevant. However, there is no explicit guidance on when to use this tool instead of alternatives such as get_desk_view or search, nor any 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, non-destructive and a closed-world scope, so the safety profile is covered. The description adds genuine value by disclosing provenance (STOCK Act reports, one filing per trade), but says nothing about data freshness, update cadence, or what a record looks like.

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

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

A single front-loaded sentence with zero filler; the source and the per-trade filing linkage both earn their place. Nothing is repeated from structured fields.

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 one-parameter read tool with rich annotations this is close to sufficient, but with no output schema the description should hint at the shape of a returned trade (ticker, amount, date, filer) or how results are ordered and paged. 'Most recent' only appears in the schema, not the description.

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 'limit' parameter is fully documented in the schema, including its default of 25 and max of 100. The description adds no parameter detail beyond that, so the schema-only baseline of 3 applies.

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

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

The description names a specific resource — disclosed AI-stock trades from the Pelosi tracker, sourced from STOCK Act filings — which is far more specific than 'get trades'. It is distinguishable from siblings like get_investor or get_ticker, though it never explicitly contrasts itself with them or with search_stocks.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no alternative is named. Usage is only implied by the phrase 'AI-stock trades from the Pelosi tracker', which lets an agent infer this is a themed list endpoint rather than a per-investor or per-ticker lookup.

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

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

The annotations already declare read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful context beyond them by labeling the data as simulated and stating it is "not recommendations," while also clarifying that the book is a combined paper book.

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 compact sentence with a colon-delimited list, leading with the core concept ("All AI agents as one desk") before enumerating contents. Every item appears relevant and there is no filler.

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

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

With no output schema, the description does a good job enumerating the main returned sections and adding the simulated/not-recommendations caveat. It could be slightly more explicit about the response shape, but it is sufficient for a zero-parameter read-only view.

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

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

The tool has zero parameters, so there are no parameter semantics to document. Baseline 4 is appropriate because the schema and description have no parameter surface to explain.

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

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

The description states the resource specifically as "All AI agents as one desk" and enumerates the contents (combined paper book vs benchmarks, standings, overlapping holdings, latest orders, open disagreements). This clearly distinguishes it from per-agent siblings such as get_agent_positions or get_agent_activity.

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 aggregate-desk framing implies this is the overview tool rather than a per-agent detail tool, but it does not explicitly say when to use it versus alternatives or name any sibling. Usage is left to inference from the contrast with more granular 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 read-only, idempotent, non-destructive, closed-world semantics, so the safety profile is covered. The description adds modestly useful behavior: components are returned and null means 'not measured that day,' plus optional history. It doesn't say what the components are or how the score is derived (a sibling get_methodology presumably covers that).

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 compact sentence with the core reading and its range front-loaded, then scope, then the component/history caveats. Nothing is wasted, though the parenthetical nesting makes it slightly dense.

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

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

There's no output schema, so the description carries the return-value burden, and it does name the main return pieces (score, components, optional history series) and the null convention. What's missing is minor: component identities and whether the reading is daily-refreshed versus real-time.

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 both parameters are already documented in the schema, including 'layer slug' and a 1-365 day range. The description's 'omit for the whole index' and 'optional score history' restate the schema rather than adding format or edge-case detail, so baseline 3 applies.

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

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

The description names a specific resource ('AI Fear & Greed reading') and its scope ('AI stocks overall or one layer'), with a concrete value range (0-100). It is clearly distinguishable from the sibling tools, none of which return an index reading.

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

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

Usage is only implied: read the description as 'call this to get today's sentiment reading.' The one guidance given, omitting layer for the whole index, is really parameter behavior, not when-to-use-versus-alternatives routing.

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

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world behavior, so the safety profile is clear. The description adds useful context that data comes from the latest 13F filing and that omitting slug changes the result set to a list, but it does not discuss freshness, update cadence, or completeness of filings.

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 padding, and the alternate listing behavior is appended efficiently. It could be marginally clearer about what 'AI-stock holdings' means, but it earns its length.

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 one optional parameter and full schema coverage, the description covers both modes of operation and the data source. Return value details are absent, but no output schema exists, and the description still conveys that holdings or a list of investors are returned.

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

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

Schema description coverage is 100%, and the schema already documents that slug identifies the investor and should be omitted to list all tracked investors. The description restates this behavior but adds no syntax, format, or validation detail 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?

The description states a specific resource and action: retrieving an investor's AI-stock holdings from their latest 13F filing, with a fallback to listing tracked investors when slug is omitted. It is clear enough for an agent to understand the tool without opening the schema, though it does not explicitly distinguish itself from sibling tools like get_agent_positions or get_congress_trades.

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 dual behavior is implied: pass a slug to get one investor's holdings, omit it to list tracked investors. However, there is no explicit when-to-use guidance, no mention of alternatives among the many sibling tools, and no 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 declare readOnlyHint, idempotentHint, destructiveHint false, and closed-world behavior, so safety is covered. The description adds useful return-shape context: stats and member stocks ordered largest market cap first. It does not disclose what happens for invalid slugs, empty layers, or whether the limit truncates results, leaving moderate gaps.

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

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

A single sentence, front-loaded with the resource and return content. Every phrase earns its place and there is no 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?

For a simple read-only lookup with full schema coverage and complete annotations, the description conveys enough about the return content and ordering. It could be slightly more complete by mentioning the default member count or behavior when the slug is not found, but it 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 100%, so both slug and limit are documented in the schema. The description reinforces that members are returned largest market cap first, which relates to limit ordering, but adds no new details about slug format or the default limit of 25.

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

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

The description names the specific resource (a buildout layer) and what it returns (stats plus member stocks), so an agent can distinguish it from list_layers or get_buildout. It does not explicitly contrast with those siblings, which keeps it below a 5.

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

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

There is no explicit when-to-use guidance. The schema's slug description says 'Layer slug from list_layers,' which implies a list-then-get flow, but the description itself does not state when to choose this over get_buildout or list_layers.

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 safety is covered. The description adds that the payload is explanatory reference material (schedule, conventions, citation rules), but it doesn't say whether the content is static or changes with the refresh cycle, nor how large or structured the response is.

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 listing the covered topics with zero padding. Slightly list-like grammar, but every element names real content the caller will receive.

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

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

With no output schema and no annotations describing the payload shape, the description must carry the return-value burden. It enumerates the topics covered but never states the format (prose, structured sections, table) or how an agent should consume it, which is the main 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?

The tool takes zero parameters, so the baseline is 4. No parameter semantics are needed and the description does not waste space inventing them.

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

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

The description names the specific content the tool returns: the AI Exposure Score tiering, the AI Fear & Greed Index, refresh schedule, data conventions and citation rules. That is enough to tell it apart from data-returning siblings like get_fear_greed, though it is phrased as a noun list rather than an explicit verb such as 'returns documentation'.

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

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

Usage is only implied: an agent can infer this is the reference tool to call when it needs to interpret the scores or cite them. There is no explicit when-to-use statement, no mention of calling it before or after get_fear_greed, and 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 readOnly/idempotent/non-destructive/closed-world, so safety is covered. The description adds genuine context beyond them: the optional-section model, that 'history' swaps 90 days for 1 year, and an explicit 'Informational, not a recommendation' disclaimer. It stops short of describing response shape or size/rate constraints.

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 payload front-loaded and the disclaimer trailing. 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?

With no output schema, the description does the necessary work of enumerating the returned fields and the opt-in extras. Slightly short of complete because it gives no sense of response size or cost when requesting all sections.

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 both parameters are already documented, including the ticker/slug duality and the enum values. The description only restates the optional sections and the history-horizon effect that the schema already states, adding no new syntax or constraint detail; baseline 3 applies.

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

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

States a specific verb+resource ('One AI-buildout stock') and enumerates the payload: price, AI Exposure Score, layers, explainer, 90 days of closes, optional sections. It is clearly the single-entity counterpart to search_stocks/get_layer, so an agent can distinguish it from siblings without opening a 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?

Usage is only implied: fetch one stock by ticker. It never says when to prefer this over search_stocks or get_layer, nor when the optional sections should be requested. No exclusions or prerequisites are given.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-derivable context: the portfolios are paper/simulated and the returns are not recommendations, which tells the agent how to frame the data. It stops short of saying how many agents exist or whether the list is stable.

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 its scope, with the disclaimer as a tight trailing clause. Nothing is wasted.

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

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

For a no-parameter read with no output schema, the description covers what is returned conceptually (agents plus since-inception return) and the data's caveat. Minor gap: no hint about list size, ordering, or what identifier to reuse when calling get_agent_positions.

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

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

The tool takes zero parameters, so the baseline is 4; there is nothing for the description to disambiguate beyond confirming the unfiltered listing 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?

Names a specific resource (AI analyst agents with public paper portfolios) and states the payload includes return since inception, so the agent knows exactly what comes back. It does not explicitly distinguish itself from siblings like get_agent_positions or get_agent_activity, but the list-vs-detail split is inferable.

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

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

Usage is only implied: a zero-parameter list tool is naturally the entry point for discovering agents before calling the per-agent getters. There is no explicit 'use this first to find an agent id' statement or any exclusion pointing at alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds the payload contents (market cap, AI exposure, 1d/7d moves), which is useful context, but no ordering, freshness, or rate-limit information beyond that.

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

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

A single front-loaded sentence that leads with the resource and packs the returned dimensions into a compact parenthetical list with no filler.

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

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

With no input schema and no output schema, the description carries the burden of describing returns, and it does so adequately by naming the metrics surfaced. Minor gaps remain (units, layer ordering, refresh cadence), but an agent has enough to decide and invoke 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 tool takes zero parameters, so the baseline of 4 applies; the description does not need to document input semantics and reasonably instead describes the output fields.

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

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

The description names the resource (buildout layers) and enumerates the exact fields returned: stock count, total and AI-exposed market cap, 1-day and 7-day moves. It does not explicitly distinguish this enumeration from the sibling get_layer (single layer) or get_buildout, so an agent must infer the list-vs-detail split from the name.

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

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

Usage is only implied by the 'list' verb and the plural resource; there is no explicit statement of when to call this versus get_layer or get_buildout, and no prerequisites or exclusions are given.

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

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

Annotations already declare the tool as read-only, idempotent, non-destructive, and not open-world. The description adds useful behavioral context by stating what the tool searches over and that it returns ids for use with fetch. It does not mention rate limits, auth requirements, or pagination, but with annotations covering safety this is a solid addition.

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

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

Two short sentences with no wasted words, and the core purpose is front-loaded. The return behavior is stated immediately after the scope, which is an efficient structure.

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 search tool with full schema coverage and rich annotations, the description provides what an agent needs: scope, entity types, and return usage. No output schema exists, so stating that ids are returned is sufficient for callers.

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

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

Schema description coverage is 100%, and the single query parameter is already documented with acceptable input types. The description reinforces the entity types but adds little syntax or format detail beyond the schema. A baseline 3 is appropriate when the schema already explains the parameter.

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 clear verb and resource: search supercyclehq.com for specific entity types. It also states the intended downstream use by returning ids to pass to fetch. It does not explicitly distinguish itself from the sibling search_stocks tool, which keeps it from a 5.

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

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

The phrase 'Returns ids to pass to fetch' implies a search-then-fetch workflow, which is useful context. However, the description does not say when to use this tool instead of siblings like search_stocks, list_agents, or get_ticker. Usage is therefore only implied, not explicitly guided.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds the useful framing that results are informational and not a recommendation, which hints at the nature of returned content. It stops short of saying how results are ordered or truncated (limit defaults live only in the schema).

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 tight sentence front-loads the core action and adds one qualifying clause. Nothing is wasted, though the disclaimer tacked on the end could be dropped or made more informative.

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, well-annotated, fully schema-documented search with no output schema, the description covers scope, filter dimensions and result intent. Ranking/ordering behavior is the only notable omission an agent might want before relying on top results.

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

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

Schema description coverage is 100%, so all five parameters are already documented, including enum-like tier values and the layer slug pointer to list_layers. The description only restates those filter concepts in prose, adding no format or combination semantics 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 (find), resource (stocks) and scope (tracked AI universe) with the filter dimensions that define it. It does not explicitly distinguish itself from sibling lookups like get_ticker or the generic search, so an agent must infer that this is the broad universe-scan while get_ticker is a single-symbol lookup.

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 by listing filter modes (name/ticker, layer, tier, minScore), which suggests when the tool fits. It never states alternatives or exclusions, e.g. whether to prefer get_ticker for a known symbol or list_layers to discover valid layer slugs before searching.

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