Attic

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that: it discloses the stub status, the auth requirement ('Requires an Attic API key'), and the fact that no comp data is returned — all things the annotations cannot convey.

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

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

Four short sentences, front-loaded with the critical 'STUB' warning so the agent sees it first. There is mild overlap between 'Does not return eBay sold prices' and 'Do not call this to price a card', but every sentence carries distinct information.

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

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

For a stub with no output schema and full annotation coverage, the description supplies the essential facts an agent needs: it is non-functional, it needs an API key, and it must not be used to price cards. The only gap is not routing the agent to the sibling that would actually serve the request.

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 itself already repeats the stub caveat for the q parameter, so the description adds no parameter-level meaning. The baseline of 3 is appropriate when the schema carries the full parameter burden.

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 plainly that this is a STUB and does not return eBay sold prices for sports cards, which prevents the agent from mistaking it for a functional comps tool. It also disambiguates from the adjacent PCGS/coin territory. However, it never states positively what the tool does return when called, only what it does not.

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

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

It gives an explicit when-not-to-use rule ('Do not call this to price a card') and a prohibition against fabricating output ('do not invent a hammer or a sold comp'), which is unusually strong guidance. It stops short of naming the correct alternative, such as attic_comps_status or attic_coin_sold_comps.

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, open-world, non-destructive operation. The description adds critical behavior beyond annotations: it is a stub that returns no sold prices, requires an Attic API key, and does not offer PCGS comps, preventing an agent from misusing it. It also warns against inventing data.

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

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

Four short sentences, front-loaded with 'STUB.' so the critical caveat is seen immediately. Each sentence adds a distinct warning or requirement: no sold prices, no pricing use, no fabrication, API key, no PCGS comps. No wasted prose.

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 four-parameter, read-only stub with full schema descriptions and rich annotations, the description supplies the essential caveats: non-functional, no sold prices, auth requirement, and PCGS exclusion. It could go further by naming an alternative tool, but the core completeness is high.

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 every parameter has a description, so the schema already carries parameter meaning. The description adds no syntax, format, or constraint details for q, days, limit, or category beyond what the schema states. 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 it is a STUB and explicitly says it does not return sold prices for coins, clarifying the resource and its negative capability. The name 'sold comps' would otherwise mislead, and the description corrects that. It does not explicitly name a sibling alternative, but the stub framing makes its purpose unambiguous.

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

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

Says 'Do not call this to price a coin' and 'do not invent a hammer,' providing a clear when-not-to-use warning plus an anti-hallucination instruction. It also notes an API key requirement. However, it names no alternative tool and gives no positive condition for calling this stub, leaving routing to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld). The description adds meaningful behavior: there is no upstream price call, PCGS comps are not offered, and the live flag gates quoting sold prices or grades.

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

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

Four short sentences, front-loaded with the core status query and followed by the key exclusions and conditional rule. Every sentence adds distinct operational value.

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

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

Given a zero-parameter status tool with no output schema, the description is nearly complete: it explains what is checked, what is not offered, and a critical downstream rule. It could be slightly stronger by naming the returned status fields, but the essential context 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?

The tool has zero parameters, so there is no parameter semantics to explain. The baseline of 4 applies because the empty schema requires no further description.

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

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

The description names the exact resources being checked (PSA cert lookup and the eBay-sold bridge) and frames the operation as a configuration/live-status query. It is specific enough to distinguish from sibling data tools, though it does not explicitly differentiate itself from attic_status.

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 conditional usage rule: if live is false, do not quote sold prices or grades. That implies the tool should be checked before quoting comps, but it does not state when to prefer this over attic_status or other sibling status tools.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description is freed to add scope context — it discloses the excerpt's 400-character cap and explicitly bounds the tool away from full article HTML. That output-shape boundary is real added value beyond the annotations.

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

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

Three short sentences: identification and return fields first, then the excerpt constraint, then the scope exclusion. Nothing is redundant and the most decision-relevant information leads.

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

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

With no output schema, the description carries the burden of describing returns and does so by enumerating the exact fields, plus a size bound on the excerpt. For a single-required-param read tool, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% for the single 'slug' parameter, including a format example (nolan-ryan) and its source (attic_list_articles). The description's 'by WordPress slug' phrasing adds only marginal meaning over the schema, so the 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 (Get) and resource (one atticcapital.com article) keyed by WordPress slug, and enumerates the returned fields (title, date, excerpt, markets, dossier slugs, episode numbers). This clearly separates it from attic_list_articles, attic_get_dossier, and attic_get_episode.

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 'Do not fetch the article HTML' line is a genuine exclusion, and the schema notes the slug comes from attic_list_articles, implying the list-then-get workflow. But the description itself never says when to prefer this over siblings like attic_search or attic_get_report_entry; usage is only implied.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower; the description still adds real value by disclosing the window semantics (since the prior weekly cut) and the empty-result meaning, 'An empty list means the rosters did not move.'

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

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

Four tight sentences, front-loaded with the resource definition before usage, parameters, and edge-case behavior. Nothing is wasted, though the layer restatement is mildly redundant with the schema.

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

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

For a zero-required-parameter read tool with no output schema, the description conveys what the ledger contains and how to interpret an empty result, which is the key behavioral gap. It does not sketch the return shape, but the conceptual coverage is otherwise 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 coverage is 100%, so the schema already documents all three optional parameters, including layer values and the YYYY-MM-DD format for since. The description largely restates that these are optional and repeats the layer=beyond mapping, adding no new syntax or constraints, so the 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 resource and scope: a 'ledger of roster and gathering moves since the prior weekly cut', plus concrete content types (rank moves, entrants/leavers of a top 5). It is distinguishable from siblings like attic_list_gatherings or attic_get_market_report, though it never names them 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?

Gives an explicit usage trigger, 'Use this for "what changed", rank moves, names that entered or left a top 5', which tells the agent the question shapes this tool answers. It does not name alternatives or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, and openWorld, so the safety profile is covered. The description adds behavior annotations don't: an API key is required for Attic Beyond, unknown slugs return 404, and the corpus is limited (~38 briefs). It does not describe response shape, but that is secondary 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?

Front-loads the purpose and payload, then appends terse operational facts in short sentences. Every sentence carries information, though the string of clipped fragments reads slightly staccato rather than polished.

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

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

With no output schema, the description carries the burden of describing returns and does so explicitly (thesis, risk flags, related episodes, outbound links), plus auth, error behavior, and corpus scope. An agent has everything needed to call it correctly.

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

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

Schema description coverage is 100% – both market and slug are documented in the schema, including the accepted market names and slug provenance. The description adds only the caution "Do not invent a dossier," which is guidance rather than parameter meaning, so the 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 ("Get an Attic object dossier") and enumerates the payload (thesis, risk flags, related Creators episodes, outbound links), which separates it from generic reads like attic_get_article or attic_get_episode. It does not explicitly contrast itself with those siblings, so it falls just short of the top band.

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 real usage context: where slugs come from ("Slugs appear on articles and episodes"), the auth requirement for Attic Beyond, and the failure mode ("Unknown slugs 404"). It stops short of naming an alternative (e.g., attic_search to discover slugs), so no explicit when-not guidance.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful behavioral context by stating the tool is public and naming the returned fields, though it does not cover error or pagination behavior.

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

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

Three short sentences are front-loaded with the core action, followed by parameter preference and return details. There is no wasted text.

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 two well-documented optional parameters and no output schema, the description provides enough detail about inputs, access, and returned content for an agent to call it correctly.

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

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

Schema description coverage is 100%, and the schema already explains both the slug and episode number parameters, including that episode is preferred. The description reinforces this but adds no new parameter 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 and resource: get one Creators episode by number or slug. The singular scope distinguishes it clearly from the sibling list_episodes tool without needing to name it.

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

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

Gives clear usage context by saying to prefer the episode number when available and noting the tool is public. It does not explicitly compare against alternatives such as list_episodes, so it stops short of a 5.

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

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, so the bar is low, yet the description adds real context beyond them: Week-0 levels default to 100 until scored, peer feeds may be 'stub_until_licensed' (data-quality caveat), Attic Beyond requires an API key (auth need), and an anti-hallucination instruction ('Do not invent index levels'). It does not describe return format or pagination, keeping it from a 5.

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

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

It is appropriately short and front-loads the core purpose, but it reads as a series of telegraphic fragments ('Peer feeds may be stub_until_licensed', 'Attic Beyond: needs an API key') that are cryptic without surrounding context. Every sentence carries content, but the structure is choppy rather than cleanly ordered.

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

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

With no output schema, the description carries some return burden; it conveys that the output is composite 'levels' with Week-0=100 semantics and stub caveats, which is enough to set expectations. It stops short of describing the actual response shape, but for a read-only index lookup with clear data caveats it is largely complete.

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

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

Schema coverage is 100%, so the schema already documents the market slugs, establishing a baseline of 3. The description adds genuine meaning beyond the schema by stating the behavior when the parameter is omitted ('Omit market for the full package'), clarifying the optional parameter's default scope.

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

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

Names a specific verb+resource ('Attic Market Strength composites') and enumerates the four covered markets (rare coins, sports cards, collector cars, fine art). It draws a boundary against a related-but-different concept ('the Price Indexes pillar of the weekly report'), though it doesn't name the sibling tool it is not (e.g. attic_get_market_report) directly. An agent can largely tell what 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?

Gives one clear invocation rule ('Omit market for the full package') and an auth note ('Attic Beyond: needs an API key'). However, there is no explicit when-to-use-this-vs-(attic_get_market_report/attic_list_markets) guidance, so alternatives must be inferred from the closing boundary statement. Usage is implied rather than spelled out.

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

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

Annotations already cover read-only/idempotent safety, but the description adds non-obvious context: layer=beyond is the paid Attic Beyond tier and requires an API key. It doesn't discuss pagination or result shape, but that is minor for a single read.

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

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

Three compact sentences, front-loaded with the core action and followed by precise routing conditions and the auth caveat. Every clause earns its place.

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

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

All three required parameters are documented and the tool's output is characterized ('top-5 roster'). With no output schema, the description could say more about return shape, but for a simple list-style read it is essentially sufficient.

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 all three parameters with allowed values. The description reinforces the layer/pillar distinction ('a Headlines / Beyond pillar') but adds no format or syntax detail beyond what the schema provides, 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?

States a specific verb and resource ('Get one weekly top-5 roster') narrowed by the three required dimensions (market, layer, pillar). An agent can distinguish this from attic_get_report_entry and attic_search without reading either 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?

Explicitly routes alternatives: 'For the paragraph on one rank, call attic_get_report_entry. For a name across pillars, use attic_search.' It also lists the trigger phrasings ('top 5', 'who is in the report'), leaving little to inference.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive). The description adds genuine behavioral context beyond them: 'The excerpt is not the whole page' warns the agent the returned content is truncated, and the layer=beyond note signals a paid-tier boundary. It stops short of describing pagination or exact response shape.

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

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

Four compact sentences, front-loaded with the core action before the requirement and caveat details. No filler, though the short sentences have a slightly clipped, note-like rhythm.

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 4-parameter read tool with no output schema, the description conveys the returned payload (summary plus short expanded excerpt) and the truncation caveat. The only gap is that it says nothing about how a missing rank or invalid market/pillar is handled.

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 are already documented, including rank 1-5 default 1 and the layer values. The description largely restates the schema (rank range/default, layer=beyond) with only the minor gloss that beyond equals Attic Beyond, 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 gives a specific verb and resource: 'Get one ranked name from a weekly pillar pack, with its summary and a short expanded excerpt.' The word 'one' distinguishes it from whole-report siblings like attic_get_market_report, though it never names those alternatives directly.

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

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

It states prerequisites ('Requires market, layer, and pillar') and the rank selector, which implies when the tool applies, but gives no explicit when-to-use guidance or routing against siblings such as attic_get_market_report or attic_list_pillars.

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, so the safety profile is covered. The description adds real behavioral value on top: the result ordering ('Newest first') and the explicit output boundary (excerpts, never full bodies).

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 paragraph that front-loads purpose and returned fields, folds the three parameters plus the sort order into the tail, and wastes no words. The exclusion of full bodies is stated early where it matters.

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

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

No output schema exists, so the description carries the return-shape burden and does so adequately by naming the four returned fields. Pagination via limit/offset is left entirely to the schema, which is a small gap but not a blocking one.

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 baseline is 3; the description largely restates q, market and since semantics already documented in the schema. It also omits 'fine-art' from the market list that the schema permits, a minor discrepancy.

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 (list published atticcapital.com articles) plus the exact return fields (title, date, URL, excerpt). The 'Never the full body' clause separates it from the sibling attic_get_article without needing the schema opened.

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

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

Gives clear context that this is a discovery/listing operation and a when-not rule ('Never the full body'), which steers the agent to the detail sibling. It stops short of naming attic_get_article explicitly, so the alternative 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.

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

Annotations already cover read-only, idempotent and non-destructive behavior, so the bar is lower. The description still adds useful context the annotations lack: the data is public, the exact result ordering (newest episode number first), and the returned field set.

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

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

Three dense sentences, front-loaded with purpose and returned fields, with the ordering constraint placed last. The field enumeration is long but earns its place since there is no output schema; no filler text.

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

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

With no output schema, the description usefully enumerates the returned fields and covers search, filtering and sort order. It omits pagination behavior/defaults (though limit/offset are in the schema) and never clarifies what 'the mapped collection' means or whether the collection is fixed.

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 schema already documents q, limit, market and offset. The description restates q's search fields (title, slug, summary) and adds only a thin clarification that market filters 'the mapped collection', which is vague rather than additive. 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 (List) and resource (Creators & Cultural Icons podcast episodes) and even flags the visibility scope as public. It is clearly distinguishable from the sibling attic_get_episode (single item) by name and verb, but it never names or contrasts with any sibling 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 explains what the optional q and market parameters do, which implies when to use them, but gives no when-to-use/when-not guidance and no alternatives (e.g. attic_get_episode for one episode, attic_search for cross-collection search). Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuine trait beyond them: 'Public.' (no authentication needed), plus clarifies the data scope is the calendar rather than the report pillar. It does not describe ordering or return shape, but the annotation bar is lower.

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

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

Three short sentences, front-loaded with what it lists, then the optional filter, then the critical disambiguation. No filler and no repetition of structured data beyond a brief market mention.

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 listing tool with no output schema and full annotation coverage, the description supplies the essential scope and sibling routing. It is nearly complete, though it could note ordering or whether results are time-bounded.

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% – both limit (default 12, max 40) and market are fully documented in the schema. The description only restates 'Optional market filter', adding no syntax or semantics beyond it, so the 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?

States a specific verb (list) and resource (shows, auctions, and other gatherings on the Attic calendar), and explicitly distinguishes itself from the similarly named Gatherings pillar by naming the sibling tool attic_get_market_report. An agent can disambiguate without opening either 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?

Explicitly states the alternative for the clashing case: 'not the Gatherings pillar of the weekly report (use attic_get_market_report with pillar gatherings for that top 5).' This is a when-not plus a named substitute, which is the strongest form of routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and openWorld, so the safety profile needs no restating. The description adds real value beyond that by disclosing the fixed cardinality (four markets) and the shape of the payload (three named page types on atticcapital.com), which is the main behavioral fact an agent needs.

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, zero filler. The identity of the tool is front-loaded and the use-condition follows immediately.

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

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

With no output schema, the description carries the burden of describing the return value, and it does so at a high level (four markets, three page-URL families). It does not state the container format or whether the URLs are absolute, but that is a minor gap for a fixed, zero-argument read.

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 there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter documentation is missing.

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?

Specific verb (List) plus a precisely scoped resource (the four Attic collector markets), and it enumerates exactly what comes back: Headlines, Beyond, and Creators page URLs. The closing clause ('not a top-5 roster') signals how it differs from other roster-shaped responses, so an agent can tell it apart without opening the schema.

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

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

Gives an explicit selection condition — use it when you need the canonical page to link — plus an exclusion ('not a top-5 roster'). It stops short of naming the sibling tool that would supply a top-5 roster, so the routing is implied rather than fully spelled out.

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

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

Annotations already cover safety (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description adds genuinely useful behavioral context: the result set is fixed at 14, it is ordered, and it deliberately omits ranked names, which prevents the agent from misusing it as a ranking source.

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

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

Three tight sentences that are front-loaded with the core fact (14 pillars, in order) followed by the usage pointer and the negative disclosure. No filler or restatement of the title.

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

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

For a zero-parameter, no-output-schema lister, the description supplies the count, ordering, value range, intended downstream use, and a limitation. It does not sketch the per-pillar shape beyond the slug, but that is a minor gap for such a simple read tool.

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

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

The tool takes zero parameters, so the baseline is 4. The schema is trivially complete and the description's mention of using the slug with attic_get_market_report correctly points at the output artifact rather than inventing 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?

States a specific verb (List) and resource (the 14 locked report pillars), plus the exact count, ordering, and the range of values (Collectors through Insights In Depth). It further distinguishes itself by noting it does not return ranked names, which separates it from ranking-oriented 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?

Explicitly says to use the returned slug with attic_get_market_report, which gives the agent a clear downstream workflow. It stops short of stating when not to call it or naming a competing list tool, so it is clear context rather than full routing guidance.

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

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

Annotations already cover readOnly/idempotent/non-destructive, and the description adds substantive behavior beyond them: it is a stub, the live lookup is disabled, an Attic API key is required, and without a key it falls back to explaining Attic Beyond. It also warns against fabricating results, which is exactly the failure mode an agent needs flagged.

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?

Five short sentences, each carrying a distinct constraint, with the STUB warning front-loaded. No redundant padding, and the most decision-critical fact (stub / no grade) comes first.

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

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

With no output schema, the description must carry return semantics; it clearly states what is NOT returned but never specifies what a successful call yields beyond the API-key fallback. For a stub tool this is nearly complete, but the positive return shape remains unstated.

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

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

One required parameter with 100% schema coverage; the schema already explains that 'cert' is a PSA certification number and that the live lookup is not enabled. The description adds nothing new about the parameter itself, 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 states outright that this is a stub lookup for a PSA cert and immediately delimits scope by denying it returns a grade or population and that PCGS comps are not offered. That differentiates it from siblings like attic_card_sold_comps, though the positive purpose (what it does return, e.g. a Beyond explanation) is only implied.

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 explicit when-not-to-use guidance: 'Do not call this to answer what a card graded or sold for,' plus the PCGS exclusion. It stops short of naming the correct sibling tool to use instead, so routing is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds searchable-field scope and a value semantic (layer=beyond means Attic Beyond), which goes beyond structured data, though it says nothing about pagination, ranking, or rate limits.

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

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

Four short sentences, zero filler, and the core scope is front-loaded before the exclusions and the sibling pointer. The parenthetical about query vs q occupies minimal space for a genuinely useful clarification.

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 search tool with full schema coverage and no output schema, the description covers scope, filters, and the alternative tool. It could say more about result shape or ordering, but nothing essential to correct invocation 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%, so the baseline is 3, but the description adds real value: it disambiguates the query parameter name ('not q') and explains the layer=beyond value, neither of which the schema conveys. Market and limit semantics are left to 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 (keyword search) with an explicit scope: roster names, summaries, and expanded report copy. The negative scope statement ('does not search articles or episodes') distinguishes it from siblings like attic_list_articles and attic_get_episode without requiring the agent to open 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?

Provides explicit when-not guidance ('This does not search articles or episodes') and names a concrete alternative ('Use attic_list_articles for the article archive'). The routing condition is stated rather than left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive, openWorld behavior, so the safety profile is covered. The description still adds value by disclosing the payload contents (API version, as-of date, markets, pillars), which is meaningful because no output schema exists. It does not mention auth requirements or error behavior, but for a parameterless read-only status call that is a minor gap.

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, zero filler, with the payload contents front-loaded before the invocation rule. Every clause earns its place.

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

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

With no input parameters and no output schema, the description carries the return-shape burden and does so by listing the reported fields, and it states the primary use case. It is complete enough to call correctly; the only shortfall is the absence of any error or staleness caveat for what is effectively a freshness/diagnostic check.

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 4 is the baseline under the rubric and nothing in the description contradicts that. No parameter semantics are needed or missing.

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 (the Attic connector status) and enumerates exactly what it reports: API version, weekly as-of date, the four markets, and the 14 pillars. It clearly reads as a diagnostic/status tool rather than a data fetcher, distinguishing it implicitly from the many list/get siblings. It stops short of explicitly contrasting itself with a sibling such as attic_comps_status.

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 trigger: 'Call this first when the user asks what week the reports cover.' That is a clear when-to-use rule that an agent can act on. There is no when-not guidance or named alternative, but the intended invocation context is unambiguous.

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