DeepStack: Independent analysis of the AI economy

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds substantive behavior beyond them: the shape of the return (side label, strongest opposing case, further voices, settling tests) and the important edge-case behavior below the relevance floor, where it reports no formed side. It stops short of describing sourcing or freshness mechanics.

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

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

A single dense sentence, front-loaded with the usage trigger and followed by the return contents; nothing is redundant. It is slightly over-packed, listing several return elements in one clause chain, which costs a little readability.

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

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

With no output schema, the description carries the return-value burden and does so fairly well, enumerating side, opposing case, further voices, and settling tests, plus the relevance-floor fallback. Minor omissions remain around what 'dated and linked' sources are and how many results precede the limit-controlled extras.

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 parameters are already documented, including the limit default and 1-5 range. The description adds no syntax, formatting, or example-level detail for either parameter, so the 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 action (return the strongest case against a stated thesis) and a specific resource (claims about the AI economy), and the title reinforces it. It does not, however, distinguish itself from siblings like deepstack_sides or deepstack_docket, so an agent must infer the boundary from the names alone.

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

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

It gives an explicit triggering condition: the user states a thesis or claim about the AI economy and wants the strongest case against it. There is no when-not guidance and no alternative sibling is named for adjacent cases (e.g., when the user wants a side rather than a counter-argument), so routing is clear but not fully disambiguated.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured fields. The description adds only the scope constraint 'from today forward', which usefully clarifies default behavior relative to include_past, but discloses nothing about pagination, ordering, or empty-result handling. Given the strong annotation coverage, this is a modest but real contribution.

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 trigger condition is front-loaded in the first clause, followed by the return payload in a single dense sentence. The enumeration of returned fields is somewhat long but earns its place because no output schema exists to document the response shape.

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 must describe the return shape, and it does so thoroughly: date and precision, status, event, resolver, and story with URLs. Combined with full annotation coverage and 80% schema coverage, an agent has enough to call this correctly, though filtering behavior for the 5 optional parameters is left entirely to the schema.

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 80% across 5 parameters, so the schema itself documents most fields, including one enum. The description mentions no parameter names or semantics; it only implies the forward-looking window via 'from today forward', which loosely maps to window_days/include_past. Baseline 3 is appropriate when the schema carries the load.

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

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

The description gives a specific verb+resource: it returns 'the dated tests that will settle each story, from today forward' and enumerates the fields (date, precision, status, event, resolver, story, URL). This is clearly a forward-looking docket of resolution events, which implicitly separates it from siblings like results or tape. It stops short of naming any sibling explicitly, so an agent must 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?

'Use when the user asks what will decide a dispute, what to watch, or the next dated test' gives three concrete triggering intents, which is strong positive guidance. However, it offers no when-not conditions and does not point to an alternative sibling for adjacent questions such as what already happened.

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

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

Annotations already declare readOnly, idempotent and non-destructive behavior, so the description's added value is the shape of the answer: arguments are attributed, dated and linked, and the market snapshot is explicitly delayed and sourced. The explicit negative ('Never a score or a ranking') usefully bounds expectations, though permissions and rate limits are unaddressed.

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

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

Two sentences, front-loaded with the usage trigger before the return contract. The middle clause listing returned artifacts is somewhat dense but each item (dates, attribution, links, market source) carries real 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?

There is no output schema, so the description properly carries the return burden and does so at a useful level of detail, including the sourced market snapshot. It stops short of stating limits, pagination, or fallback behavior when no entity matches, which leaves a modest gap.

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

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

Schema coverage is 100%, so all four parameters (kind, name, slug, ticker) are already documented, including the enum and slug URL format. The description only restates that slug/ticker/name are accepted identifiers, adding no syntax or precedence guidance (e.g., which identifier wins if several are supplied).

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: look up a company or person in The Buildout by slug, ticker or name, and it enumerates what it returns (appearances, reported figures, attributed arguments, delayed market snapshot). The closing 'Never a score or a ranking' implicitly distinguishes it from comparative siblings, but no sibling is named outright.

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 an explicit trigger ('Use when the user asks what the voices argued about a company, or what a person argued') plus the accepted identifier forms. There are no named alternatives or when-not conditions, so routing between deepstack_entity and siblings like deepstack_results still requires inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower. The description still adds real behavioral context beyond them: it enumerates what the payload contains and discloses a business rule that 'no hit rate is shown until ten results exist' — a non-obvious threshold an agent would otherwise not know. It does not cover pagination or failure modes, but the added value is genuine.

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

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

Two sentences, no padding, with the usage trigger front-loaded ahead of the payload description. The middle clause ('what happened with the primary source and the number, what it did to the Call') is a slightly loose list, but 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?

With no output schema, the description carries the full burden of explaining returns, and it does list the salient fields plus the ten-results rule. But those fields are named in undefined jargon ('the Call', 'the number', 'primary source'), so an agent still cannot fully predict the shape or meaning of the response, and sibling differentiation is absent. Adequate, 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?

The tool takes zero parameters (empty object schema, additionalProperties false), so per the rubric the baseline is 4. There is nothing for the description to disambiguate, and it correctly does not invent parameter semantics.

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 does state a resource and what comes back ('the tests that came in: verdict, what happened with the primary source and the number, what it did to the Call'), which is more than a restatement of the title. However, the core noun 'the Call' and 'the number' are undefined domain jargon, and nothing distinguishes this from siblings like deepstack_docket, deepstack_tape, or deepstack_story. An agent can guess it is a results/outcome read, but the purpose is only implied rather than cleanly stated.

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

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

'Use when the user asks what resolved and how the Call fared' is an explicit trigger condition, which is better than nothing. But there are no exclusions and no routing to alternatives despite a dense sibling set (docket, tape, sides, story, search) that plausibly overlaps. Usage is implied by one fuzzy trigger phrase rather than clearly bounded.

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 annotations already covering readOnly/idempotent/non-destructive/openWorld=false, the description still adds real behavioral context: the shape of results (stories, sides, tests, entities plus canonical URLs) and the negative-result behavior (a 'no formed side' answer with up to three nearest items explicitly labeled nearest). It does not mention pagination or result ordering, so 4 rather than 5.

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

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

The routing condition is front-loaded in the opening clause and every clause carries information (trigger, return shape, fallback behavior, ordering rule). It is dense and semicolon-heavy, so it is slightly harder to scan than an ideal 5, but 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?

There is no output schema, so the description carries the burden of describing returns, and it does so including the graceful 'no formed side' fallback. Annotations cover the safety profile and the schema covers all parameters, leaving only minor unspecified details such as hit ranking or default behavior when kinds is omitted.

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 query, kinds and limit are fully documented in the schema; the description's mention of companies/people/questions loosely echoes the query semantics. Baseline 3 applies because the description adds no syntax, format or constraint detail 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 what the tool retrieves (matching stories, sides, tests and entities with canonical URLs) and its domain (the AI economy / DeepStack's published analysis). It also implicitly distinguishes itself from slug-based siblings by saying to use it first when the slug or name is not known, though it never names a sibling tool explicitly.

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

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

It gives a clear trigger (user asks where informed investors disagree, or wants published analysis on a company, person or question) and an ordering rule ('use it first when the slug or name is not known'). No explicit when-not-to-use or named alternative is provided, so it falls just short of the top band.

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 behavior, so the safety profile needs no restating. The description earns credit by disclosing what the payload contains (attributed paraphrased voices with dates and source links, the strongest case against each side, resolution tests), which is genuinely useful since no output schema exists.

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, each doing distinct work: the first routes invocation, the second enumerates the return shape. It is front-loaded with 'Use when' and contains no filler or repeated annotation content.

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 must convey the return shape and does so thoroughly, including provenance (dates, source links) and the 'what would change a side's mind' element. Only the absence of any sibling-routing or fallback guidance keeps it from being fully 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 100% for both parameters, so the schema already carries slug and part semantics. The description only restates 'one story by slug or part number' and adds no selection guidance on when to prefer part over slug, so baseline 3 is right.

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

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

States a specific verb and resource: it returns the sides of a story (DeepStack Call, attributed voices per side, strongest counter-case, crossing voices, dated tests) keyed by slug or part number. The scope is unmistakable, but the description never contrasts itself with sibling tools like deepstack_counter or deepstack_docket, leaving that disambiguation 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?

Gives explicit trigger conditions: bull/bear case, who disagrees with a thesis, the counter-argument, what would change a side's mind. That is concrete when-to-use guidance, but it names no exclusions and does not point to an alternative sibling when those triggers overlap (e.g. deepstack_counter).

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/openWorld=false, so safety is covered. The description adds real behavioral value by enumerating what a result actually contains (Call, stance, conviction, actions, key numbers, dated tests, sources with URLs), which matters because there is no output schema. It says nothing about behavior on an invalid slug/part or the relationship between the two addressing modes.

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 use-when clause is correctly front-loaded, but the rest is a single sprawling sentence with a long comma-chained enumeration of return fields. The enumeration does earn some of its length given the absent output schema, yet it would read far better as a short structured list rather than one run-on line.

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 must convey the return shape, and it does so thoroughly (headline, dek, Call components, key numbers, body, dated tests, results, entities, sources). Combined with annotations covering the read-only profile, an agent has what it needs. The gap is edge behavior: neither parameter is required, yet the description never says what happens if neither part nor slug is supplied, or whether one takes precedence.

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 all three parameters are already documented in the schema, including that part is an alternative to slug and that "summary" omits body paragraphs. The description's "by slug or part number" merely echoes the schema and adds no syntax or format detail beyond it. 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 and resource: read one Part of The Buildout in full, addressable by slug or part number. The scope (single part, full read) implicitly separates it from a search-style sibling, but no sibling is named, so it stops short of full differentiation.

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

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

"Use when the user wants one Part of The Buildout read in full" gives a clear triggering condition and the two addressing modes. There is no when-not guidance and no alternative tool named (e.g. deepstack_search for finding a part you don't yet have a slug for), so routing is only partly covered.

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 establish this is a safe, idempotent, closed-world read. Beyond that, the description discloses what each record contains — producer, date, weekly change, and as-of time — which is real behavioral context and matters more than usual because there is no output schema. It does not state freshness/polling behavior or whether the tape can ever be empty.

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

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

It is a single front-loaded sentence that opens with the usage trigger before listing payload details. The long enumeration of ten series is dense but earns its place, since no output schema exists to carry that information. Slightly run-on, but no filler.

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

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

With no output schema and no parameters, the description carries the burden of describing the return payload, and it does: the series list plus per-record fields (producer, date, weekly change, as-of time). It stops short of stating whether all series are always returned together or how large the response is, a minor gap given the closed-world annotation.

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

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

The tool takes zero parameters, which is the baseline-4 case; there is no argument syntax for the description to clarify. Schema coverage is reported at 100%, and nothing in the description misrepresents the no-argument call.

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

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

The description names a concrete resource — the macro tape — and enumerates the exact series it returns (Treasury yields, real yield, S&P 500, VIX, Brent, gas, copper, Fed funds target, CPI, payrolls), so an agent knows precisely what payload to expect. It does not reference any sibling tool (deepstack_docket, deepstack_results, etc.), so the differentiation is left to the content rather than stated.

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

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

"Use when the user asks for the macro figures DeepStack tests its notes against" gives a clear trigger condition, which is more than most tools offer. However, it names no alternative and gives no when-not guidance, so routing against siblings like deepstack_results or deepstack_search is left to inference.

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