discovery

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that exactly one answer page is returned and what its structure is, but it does not disclose error behavior, edge cases, or other hidden traits beyond the annotation baseline.

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 front-loaded with the operation and return contents, followed by a compact list of slug examples. Every sentence earns its place, and there is no vague filler or repetition of the tool name.

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

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

With an output schema present and one fully documented parameter, the description is mostly sufficient. However, only 8 of the 33 known slugs are listed and there are no enums, so the agent cannot reliably determine the complete set of valid slug values.

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

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

The schema already fully documents the single 'slug' parameter with 100% coverage and an example. The description adds the total count of known slugs and eight concrete examples, which materially improves an agent's ability to pick a valid value beyond what the schema 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 states a specific verb and resource: 'Returns one authored /answers page as structured content,' and enumerates exactly what that content includes. This clearly distinguishes the tool from sibling content-getters by naming the unique '/answers page' resource.

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 'Known slugs' list implies when the tool is applicable, and the resource type suggests it is for retrieving pre-authored answer pages. However, the description does not explicitly say when to prefer this tool over a sibling, nor does it mention any exclusions or alternative tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by explaining the product/persona filters and that status opts into drafts, which clarifies the default live-only behavior beyond the structured annotations.

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

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

The description is compact and front-loaded with the core purpose. The telegraphic style is efficient, though the term 'SB7-shaped' is unexplained jargon that may reduce clarity for agents unfamiliar with StoryBrand terminology.

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

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

Given the read-only nature, full schema documentation, and presence of an output schema, the description covers the essential information: what the tool returns and how filtering works. It could optionally note what happens when no filters are applied or how to choose this over sibling tools, but these are minor gaps.

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

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

Schema description coverage is 100% with all three parameters documented, including the status enum and default. The description mostly restates the filter behavior without adding deeper semantic detail like format, examples, or edge-case behavior, 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 clearly identifies the resource: per-persona StoryBrand arguments for each product. It specifies the exact content layer (SB7-shaped, major problem solved and solution look) which distinguishes it from the other sibling get_* argument tools.

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

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

The usage is implied through the phrasing 'per-persona StoryBrand arguments' and the filter syntax, but there is no explicit when-to-use or when-not-to-use guidance, nor any reference to alternatives among the many sibling retrieval tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds valuable behavioral nuance beyond that: 'oftenMeans' is 'a labelled heuristic, never a conclusion.' It also conveys that the tool exposes a fixed, closed vocabulary of 7 shapes and 33 forms, which helps the agent calibrate expectations about what it will receive.

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

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

The description is compact at three sentences, but the first sentence nearly repeats the title verbatim, providing little additional value. The second sentence is conceptually rich but indirect, and the third delivers a genuine caveat. It is appropriately sized but not optimally efficient.

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

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

Given the single optional parameter, the presence of an output schema, and read-only annotations, the description covers the essential context: what the vocabulary contains, the shape-to-form relationship, and the heuristic caveat. It could be more complete by explicitly stating the default behavior when no 'shape' filter is provided, but this is minor.

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 single optional 'shape' parameter is already well-documented with an enum and a description. The description reinforces the conceptual role of shapes ('7 data shapes') but adds no syntax, filtering behavior, or value-specific guidance beyond what the schema provides. 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?

The description identifies the resource precisely: 'The canonical form vocabulary' with '7 data shapes and the 33 canonical forms they resolve to.' The tool's purpose as a structural reference is clear. It does not explicitly use a verb like 'retrieve' or 'list,' and it does not directly compare itself to siblings, so it stops short of 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 description implies usage context: canonical forms are the structure that lets one engine interpret cross-domain metric data, so an agent should consult this when needing the structural vocabulary rather than domain-specific rewrites. However, it never explicitly states when to use this tool versus alternatives or when it should not be used.

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 description goes well beyond the read-only and non-destructive annotations, explicitly stating that results are discourse, not evidence, that book frequency is confounded, and that results are never reported as corroboration, confidence, or score. It also discloses that single-work claims are returned and that corpus-level stats are not returned, including an openly stated counting discrepancy.

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 dense but efficient; each sentence contributes either the core function, the return content, or critical caveats. The warning is front-loaded and reinforced without becoming redundant enough to hurt usability.

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

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

Given the output schema exists and annotations already mark this as read-only and non-destructive, the description sufficiently covers return semantics, limitations, and the non-evidentiary nature of the data. It could be more explicit about how the four schema parameters map to the three query modes, but the schema descriptions mostly fill that 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 input schema already covers all four parameters with descriptions, so the baseline is 3. The description adds useful context about construct pairs and focus areas, but it does not substantially deepen the meaning of individual parameters beyond what the schema states.

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

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

The description clearly states the tool counts how many distinct works discuss a claim and names them with rationale. It also draws a sharp distinction from evidence or corroboration, making its purpose unique among the sibling tools.

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

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

The description gives clear context about when the tool is appropriate: for discourse volume from the book corpus, not for evidentiary support. It warns that corroboration is not required, but it does not explicitly name alternatives or provide explicit when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context on top: the result is an ordered array, and the awareness parameter can reshape the sequence for the buyer's state. No contradiction with annotations.

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

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

The description is short, but its first sentence exactly duplicates the tool title. The second sentence carries valuable information, but the redundant opener wastes a sentence and slightly dulls the front-loading effect.

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, two-parameter tool with an output schema and annotations, the description covers the core purpose, the main selector parameter, and the optional reshaping behavior. It does not discuss alternative tool selection, but that gap is relatively minor for actually invoking this tool 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 description essentially paraphrases the schema (pitch slug, awareness state). It adds no new constraints, formats, or usage details beyond what the input schema already provides, 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?

The description uses a specific verb ('serves') and a specific resource ('a named pitch as an ordered InsightCard[]'), making the tool's function immediately clear. It also differentiates itself from the many get_* siblings by naming the unique output type and the 'cross-site insight-player contract'.

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 explains how the tool works (?pitch selects, ?awareness reshapes) but gives no guidance on when to use it instead of alternative get_* tools, nor any conditions or exclusions. An agent is left to infer that this is the right tool whenever InsightCards are needed.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral detail beyond that: IDs are SHA-256 of normalized title|authors|year, stable across repos, and the export excludes works whose canonical home is elsewhere. This helps an agent understand exactly what data is returned and how IDs are derived.

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 well-structured and informative, placing the core purpose first then adding id-derivation and scope details. There is minor redundancy with the title and the repeated 'works homed here' phrasing, but each sentence contributes useful 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?

Given the rich output schema, fully described parameters, and annotations covering safety, the description is complete. It clarifies the id-stability mechanism, the exclusion rule, and the join use case, leaving no significant gap for an agent to invoke 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%, so the parameters tag and limit are already fully documented. The description adds no additional parameter-level guidance, which is acceptable given the schema's clarity, but it doesn't go beyond the baseline.

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

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

The description clearly identifies the tool as a batch export of library_id rows for works homed on peopleanalyst.com, listing the exact fields (id, title, author, year, property tags). It also distinguishes itself by emphasizing content-addressed stable IDs, which separates it from generic catalog feeds and sibling tools.

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

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

The description gives clear context: use this when you need stable content-addressed IDs to join to the catalog without string matching, and it explicitly scopes to works homed here, excluding titles whose canonical home is another property. It does not name specific sibling alternatives or state when-not-to-use explicitly, but the usage context is unambiguous.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context: cards are cross-site marketing assets assembled from brandscripts and proofs, and filters restrict results to one product or lifecycle. No contradiction with annotations.

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

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

The description is compact and readable, but the opening sentence largely repeats the tool title verbatim, and the next sentence partially overlaps with it. It is not bloated, but there is minor redundancy.

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 an output schema present and read-only annotations, the description covers the key usage context: what the registry contains, its provenance, and available filters. It does not explicitly explain how personas are returned, but the output schema handles return structure.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the filter semantics and adds that product filters to one product, but it does not materially enrich beyond the schema's parameter descriptions.

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 Pitboss marketing-asset registry, and clarifies its contents as typed cards plus personas built from brandscripts and proofs. It is clear about the resource, though it does not explicitly differentiate itself from sibling get_brandscripts or get_insight_cards.

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 conveys the domain and optional filters (?product, ?status), giving some sense of when to call it. However, it does not state when to prefer this tool over sibling get_* tools or provide explicit exclusion/alternative 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 indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: the data is versioned, CORS-open, and 'assembled from canon,' which informs an agent about stability, accessibility, and source trustworthiness. There is no contradiction with annotations.

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

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

The description is front-loaded with the core purpose, then expands into a concise field list and ends with a usage note. The comma-separated field enumeration is dense but useful and not padded. It earns a 4 rather than 5 because the field list is somewhat long and the 'Machine-readable description' phrasing repeats 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?

This is a simple read-only tool with one optional parameter and an output schema, so the description does not need to explain return values. It provides the filter mechanism, data scope, versioning, CORS access, and source provenance. An agent has enough information to invoke the tool correctly without additional clarification.

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 input schema already covers the single optional 'product' parameter with a description and examples, giving 100% schema description coverage. The description's 'Pass ?product to filter' adds query-parameter syntax but not substantial semantic meaning beyond the schema. This matches the baseline for high schema coverage.

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

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

The description states a specific action and resource: retrieving machine-readable descriptions of PeopleAnalyst products. It enumerates the exact fields returned (name, category, oneLiner, problemFrames, etc.), which removes ambiguity and distinguishes it from the sibling get_* tools. The title reinforces the purpose without contradiction.

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

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

The description gives clear context for when to use it: when you need versioned, CORS-open, machine-readable product portfolio descriptions. It also provides a concrete usage instruction with 'Pass ?product to filter.' It does not explicitly name alternative tools 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 establish read-only and non-destructive behavior, so the bar is lower. The description adds useful behavioral context: drafts are excluded by default unless status=all, and persona relevance is derived from focus via a stated heuristic rather than a direct mapping. It also explains the falsifiability semantics, which an agent could not infer from annotations alone.

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 short and front-loaded with the core concept, but the first sentence repeats the title verbatim and 'The cards a story is told with' is metaphorical rather than informational. The remaining behavioral details are useful and compact, but some words could be trimmed without losing 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 read-only tool with full schema coverage and an output schema, the description provides enough conceptual and behavioral context for an agent to call it correctly. It explains the default status behavior and the core semantics of scene templates. The missing usage exclusions are already captured under usage guidelines, so this dimension remains fairly 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?

The input schema has 100% description coverage, with meaningful descriptions for all 8 parameters and enums for tier and status. The description adds some extra meaning around status and persona/focus, but does not expand on id, form, shape, or archetype. Since the schema already carries the heavy lifting, the baseline score of 3 is appropriate.

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

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

The description clearly identifies a specific resource—falsifiable scene templates—and explains what they are: one claim plus what would make it false. It lacks an explicit verb like 'list' or 'fetch', but the tool name and context make the retrieval purpose obvious. It is distinct enough from sibling tools by focusing on scene templates with truth conditions.

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

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

No guidance is given about when to use this tool versus any of the many sibling get_* tools. The only conditional statement, 'Drafts excluded unless ?status=all', describes a filter behavior rather than a use-case selector or alternative tool. An agent is left to infer when scene templates are the right resource.

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

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

Annotations already mark the tool read-only and non-destructive, so the description only needs to add contextual behavior. It adds that status can opt into drafts and that product filters scoping, which is useful, but it does not describe pagination, empty results, or related behavioral nuances. No contradiction with annotations.

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

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

The description is compact and front-loads the core concept, then gives the query-parameter hints. There is a minor redundancy: the first clause duplicates the title verbatim, but the rest of the sentence earns its place by adding the proof-layer and product-situation context.

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

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

For a read-only tool with two optional parameters and an output schema, the description adequately explains the resource and the available filters. It could clarify the 'discovered → diagnosed → solved' lifecycle, but that omission is not blocking given the schema and low invocation complexity.

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 both parameters are well documented (status enum with default, product filter). The description's '?product filters; ?status opts into drafts' largely restates the schema rather than adding new meaning, so the schema carries the 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 identifies the resource as 'Demonstration scenarios' and clarifies them as 'the proof layer paired with brandscripts: concrete situations a product resolves.' This is more specific than the bare title, though it doesn't explicitly state a retrieval verb beyond the tool name or directly contrast with a sibling.

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

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

It implies when to use the tool by describing scenarios as proof-layer evidence for brandscripts and mentions filtering by product and opting into drafts, but it never explicitly says 'use this when' or names alternatives like get_brandscripts. The context is clear but exclusion/selection guidance is absent.

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 description adds meaningful behavioral context beyond the readOnlyHint annotation: the returned stories are pre-authored candidates only, and nothing asserts they are true of any organization until decided against data. This is a valuable caveat that shapes how an agent should interpret results. It does not contradict the annotations.

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

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

The description is compact and front-loaded, but the first sentence essentially repeats the title verbatim ('Pre-authored data-story tracks — the possibility space'). The rest is dense and useful, though the filter list in shorthand is somewhat awkward. Overall it is concise but includes avoidable redundancy.

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

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

Given the readOnly annotation, full schema coverage, and presence of an output schema, the description covers the essential semantics well: what a story track contains, that results are candidates only, and the available filters. It could be more explicit about behavior when no filters are provided, but no critical operational gap remains.

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 slug, metric, persona, and problem. The description merely lists the same filters in shorthand ('?persona / ?problem / ?metric / ?slug filter') without adding semantics like combination behavior or default results when no filters are supplied. 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 identifies the resource as pre-authored data-story tracks and clarifies what they contain: the SB7 argument, acts/beats, branches, decision, and required data. It also differentiates the tool's scope by emphasizing that these are candidates, not validated truths. However, it lacks an explicit action verb like 'fetch' or 'list,' relying on the tool name to supply 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?

Usage is implied by the filter list and the 'candidates only' caveat: an agent would use this to explore possible story tracks before testing them against data. There is no explicit guidance on when to prefer this tool over siblings such as get_insight_cards or get_scene_templates, and no alternatives are named.

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

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

Annotations already mark it as read-only, but the description adds meaningful behavior beyond that: auth-gated REST + MCP access, open discovery vs. gated execution, and a production caveat about `grounded: false` and HO-2512. This helps the agent set expectations about output reliability.

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 dense and informative, but the opening sentence is an exact repetition of the title, wasting the first slot. The unexplained 'Bicycle answer' phrasing also adds jargon without clarifying meaning, though the rest of the description is reasonably front-loaded and compact.

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

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

Given the output schema exists and annotations cover the safety profile, the description supplies the remaining needed context: what the catalog contains, how it is accessed, auth requirements, filtering options, and even a production-behavior caveat. Nothing essential is missing for an agent to call this tool 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 coverage is 100%, and the description mostly restates what the schema already documents (`?category filters by family; ?slug returns one tool`). It adds little semantic value beyond the schema, 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?

Clearly identifies itself as a machine-readable catalog of acting tools, listing what each tool contains and how it can be queried. The `?slug returns one tool` phrasing anchors a concrete retrieval behavior, and the catalog framing distinguishes it from all the sibling `get_*` tools.

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

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

States that discovery is open and describes the intended use ('find + cite the tools'), while noting that execution is API-key gated. It gives clear context for when to use this catalog tool, though it does not explicitly name alternatives or say when not to use it.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds useful context: the feeds are free and machine-readable, availability is described for MCP/REST, and an OpenAPI endpoint is published. No behavioral contradictions exist.

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

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

The description is two sentences, with the core purpose front-loaded and the supplementary OpenAPI link placed second. Every sentence adds value without redundancy.

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 parameterless, read-only listing tool with an output schema and clear annotations, the description fully equips an agent to select and invoke it. The OpenAPI link also provides an external reference for further detail.

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, and the schema coverage is 100%, so there is nothing for the description to clarify. The baseline of 4 applies because no parameter documentation is needed.

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

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

The description uses a specific verb ('List') and names the exact resource ('PeopleAnalyst's free machine-readable feeds') plus the key attribute ('their MCP/REST availability'). This clearly distinguishes it from the sibling get_* tools, which retrieve specific content rather than listing available feeds.

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 that the tool is for discovering available feeds, but it does not explicitly say when to use this tool versus alternatives, nor does it state any exclusions. The intended use is reasonably inferable from the verb and resource, but not 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?

The description goes well beyond the readOnly/destructive annotations by explaining the ranking methodology: information-per-friction, entropy from the discrimination matrix, governance outweighing effort, and equal weighting of live stories absent priors. It also discloses that the output includes both immediate and legal-review-needed asks, which is useful behavioral context beyond what annotations provide.

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

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

The description is dense and mostly front-loaded, opening with the core question before explaining ranking details. It repeats the title almost verbatim, which is mildly redundant, but every major sentence adds useful information about outputs, assumptions, or invocation. It earns a strong score despite being slightly verbose.

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 complex planning tool, the description is remarkably complete: it states the outputs, the ranking formula, the fairness assumption, the legal-review split, and the query parameter syntax. Since an output schema exists, the description does not need to explain return value structure. An agent has enough information to understand what the tool does and when to call it.

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

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

The input schema is a generic body object with no property-level detail, so the description must carry the parameter-semantics burden. It does so by naming the GET query parameters (?live=, ?have=, ?lack=) and specifying comma-list format. However, it does not explain the semantic meaning of each parameter, such as precisely what live, have, and lack represent, leaving some inference to the agent.

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 purpose: given candidate data-stories, return the single most efficient next question, a full ranked list, and the minimum set of asks needed to make every live story testable. This clearly distinguishes the tool from the sibling get_* tools because it is a planner/optimizer, not a simple fetcher.

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

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

The description gives clear usage context: use when you have candidate data-stories and need to decide what data to ask for next, including a split of what can be sent today versus what needs legal review. It also references the query parameters live, have, and lack, which signals how to invoke it. It does not explicitly name alternative tools or say when not to use it, but the context is strong enough for an agent to select it appropriately.

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

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

Annotations already mark it read-only and non-destructive; the description adds substantial behavioral disclosure: determinism, 5,000-row cap, caller-supplied data, no retention, and input modality restrictions. These are meaningful operational traits an agent needs and are not present in the annotations.

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

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

The description is compact and information-dense after the initial title-like sentence. It front-loads capabilities and then adds constraints; the mild redundancy between title and first sentence prevents a 5.

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

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

The description covers purpose, input nature, limits, determinism, privacy, and scope, which is strong for a complex tool. Because an output schema exists, the absence of return-value details is acceptable; the only notable gap is body schema internals, already reflected in parameter semantics.

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

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

The schema only exposes a generic 'body' object, so useful meaning must come from the description. The description explains the high-level payload intent (numeric vectors and modes) but does not specify required fields, formats, or mode-selection keys, leaving a gap for invocation.

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 specific operations ('cluster subjects, discover roles from behaviour + relationship edges, detect emergent roles, or match against exemplars') on a defined resource (caller-supplied numeric vectors). The title and description align, and the deterministic, non-biometric framing separates it from the read-only get_* 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 clearly conveys when to use this tool: when behavioral segmentation, role discovery, or exemplar matching is needed over caller-supplied numeric vectors. It adds exclusions (no audio/video/affect inference, no retained data) and constraints that define suitability, though it does not explicitly name alternative tools or contrast them.

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