particle-pro

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

Annotations declare destructiveHint=true and openWorldHint=true, so the description is not obligated to restate mutability. It adds valuable context beyond the annotations: the active-alert billing transition with an explicit confirmation requirement, the paused-alert exception, the silent backfill of the past week, the verified/pending recipient behavior, and the zero-data-retention exclusion for alerts. It does not, however, explain why destructiveHint is set (e.g., what gets removed or overwritten), which is a modifier worth flagging.

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 organized, with a clear creation paragraph followed by separate paragraphs on entity vs. keyword, filters, billing, and post-creation behavior. However, it is long and repeats some schema content (the keyword phrase semantics, the speaker_roles replacement behavior), which inflates length without adding new information for those points.

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 10-parameter tool with a nested filters object, no output schema, and mutation semantics, the description covers the full end-to-end workflow: resolve, preview, create, backfill, downstream ids, billing consent, and retention caveat. Nothing an agent needs to invoke it correctly 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. The description adds meaning beyond the schema on several parameters: the double-quoted phrase matching semantics for `keyword` and the requirement to explain the phrase in `description`; the interaction between `filters` and every downstream surface; the REPLACES-not-intersects behavior of `speaker_roles` and the error when sent with ENTITY_MENTION; the billing effect of `is_active`; and the chaining guidance for `output_format`. This goes beyond the schema text for several fields.

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

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

The description states a specific verb and resource ('Create an alert that watches a single entity') and enumerates the three kinds of signal it can watch (ENTITY_MENTION, PODCAST_SPEAKER, KEYWORD_MENTION). It distinguishes itself from siblings by naming particle_alert_preview as the pre-commit alternative and listing downstream alert tools that consume the returned id.

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-to-use rules: use ENTITY_MENTION with a slug from particle_entity_resolve; fall back to KEYWORD_MENTION when there is no slug or no podcast coverage; run particle_alert_preview before committing. It also routes the agent to the resolve tools by name and states that one alert covers one entity, so multi-entity coverage means multiple calls.

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 known. The description adds useful behavioral context: it notes the 'filters' section is omitted when none exist, explains that include embeds additional data, and warns that JSON output is 'larger and noisier for an LLM to read.' It does not contradict annotations. It doesn't cover pagination or rate limits, but those are delegated to the sibling tool.

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

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

The description is a single, well-organized paragraph that front-loads the core purpose, then flows naturally into optional includes, then the sibling pointer. Every sentence earns its place—no filler or redundancy. The structure makes it easy for an agent to quickly extract the key decision points.

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 tool with 4 parameters, no output schema, and rich annotations, the description covers all necessary operational aspects: default return, optional sections, parameter usage, output format guidance, and redirection to the sibling for extended functionality. Nothing essential is missing 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 coverage is 100% and each parameter already has a description. The description adds value by explaining the default behavior of include (not specified in schema) and providing rationale for choosing output_format (markdown vs json), including a caution about JSON verbosity. It also clarifies the relationship between match_limit and include, reinforcing the schema's default of 5. This goes beyond mere repetition.

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 a specific verb ('Fetch') and resource ('a single alert's full configuration'), enumerates the content (title, kind, cadence, watched entities, emails, filters), and explicitly differentiates from the sibling tool particle_alert_list_matches by noting it returns the full paginated history. This leaves no ambiguity about the tool's role.

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 provides explicit usage guidance: it explains the default behavior (configuration only), how to request embedded sections via include, and directly instructs when to use an alternative tool ('For the full, paginated match history with transcript excerpts, use particle_alert_list_matches'). It also clarifies when to use output_format=json (programmatic chaining) vs markdown, covering both when and when-not to use this tool.

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 and destructiveHint, so the safety profile is covered. The description adds useful behavioral detail: results are newest-first, each entry carries the alert id, and this is scoped to the current project. This goes beyond the annotations without contradicting them.

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

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

Two compact sentences with no filler. The main behavior is front-loaded, and the downstream routing adds high-value guidance without bloating the description.

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 list tool with no output schema, the description gives the essential return clue (each entry carries the alert id) and ordering. It does not enumerate all entry fields, but it provides enough for an agent to decide to call the tool and to chain into the appropriate follow-up 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?

Schema description coverage is 100%, so the input schema fully documents limit, cursor, and output_format. The description adds no parameter-specific details but is not required to; it stays at the baseline because it does not enrich parameter meaning beyond the schema.

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

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

The description clearly states the operation ('List the alerts in your project'), the resource, and the ordering ('newest first'). It also distinguishes itself from sibling tools by explaining what each entry's id can feed into, making it easy to tell apart from particle_alert_list_matches and particle_alert_get.

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 establishes the listing use case and tells the agent what to do with the returned alert ids, routing to get, list_matches, update, or delete. It does not explicitly state when not to use this tool versus create or preview, but the intended context is clear enough.

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. The description adds useful behavioral details beyond those annotations: results are newest-first, optional view=detailed changes payload richness, and backfilled matches are flagged and never triggered an email. 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?

Three tight sentences front-load the core purpose, then add the most decision-relevant parameter guidance and one important data nuance. No redundant restating of schema fields; 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?

For a read-only list tool with full schema coverage of all 7 parameters and annotations covering the safety profile, the description supplies the missing result semantics (match contents, slugs, excerpt behavior, backfill flag). An agent has what it needs to select and call this 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%, so the baseline is 3. The description adds extra semantic value by explaining what view=detailed yields (transcript excerpts), what after/before do (date-range scoping), and how returned slugs connect to particle_podcast_get_episode / particle_podcast_resolve.

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 opens with a specific verb and resource ('List the matches an alert has caught') and adds ordering ('newest first'), making the tool's job unmistakable. It also clarifies what a match contains (watched entity, podcast episode, slugs) and differentiates this from alert-lifecycle siblings like particle_alert_list.

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

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

The phrase 'the payoff of an alert' gives clear context for when this belongs in a workflow, and the description gives direct guidance for optional behavior ('Use view=detailed... after/before...'). It does not explicitly name alternatives or state when not to use the tool, so it stops short of a top score.

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 (readOnlyHint=false, destructiveHint=false) are minimal and all-negative, so the description carries the behavioral burden and discharges it exceptionally. It discloses the background sweep and caching side effect (which explains why readOnlyHint=false), the non-destructive guarantee, the upper-bound caveat when relevance=RELEVANT, and which filter axes actually narrow the historical sweep vs which are read-time projections. No contradiction with annotations; the side-effect disclosure actually reconciles the readOnlyHint=false flag.

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 (~120 words) but logically ordered: purpose → mechanism → usage workflow → filter semantics → side-effect caveats. Every sentence carries distinct information and the purpose is front-loaded. Slight deduction for redundancy, since the filter projection/upper-bound caveat is restated in the schema's filters.description, making the overall definition longer than strictly necessary.

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 6-parameter tool with sparse annotations and no output schema, the description covers the essentials well: return content (count, breakdown, sample), non-destructive behavior, filter semantics, and the create-workflow link. The main gap is the sync/async ambiguity — it says 'starts a background sweep and caches its progress and results' without clarifying whether the call blocks for the sweep or returns immediately with progress, nor how to retrieve the cached results afterward. A minor gap given the otherwise thorough coverage.

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

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

Schema coverage is 100% with rich per-parameter descriptions, so the baseline is 3. The tool description adds genuine cross-parameter orchestration value: it ties entities/keyword to the derive-from-create workflow, and clarifies which filters (languages, speaker_roles) narrow the sweep vs which (relevance, source_popularity) are projections that leave the count unchanged. It stops short of 5 because individual parameter semantics are already exhaustively documented in the schema.

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

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

The opening sentence 'Preview how often an alert would fire BEFORE creating it' grounds the tool with a specific verb and resource, and the description further specifies the mechanism (sweep past N days), return values (match count, per-day breakdown, sample), and explicit exclusions ('does not create an alert or send notifications'). It clearly differentiates from siblings: it is not particle_alert_create (no creation), not particle_alert_get/list (no existing-alert read), and not particle_alert_list_matches (no live-match listing).

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 explicit when-to-use guidance: 'Use this to size an alert (REALTIME vs DAILY vs WEEKLY cadence) or to confirm the entity slug watches the right thing.' It also names the exact continuation workflow — 'then call particle_alert_create with the same entity slug' — and instructs the caller to reuse planned filters. This is turnkey routing to the correct sibling.

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?

Adds substantial context beyond the destructiveHint/openWorldHint annotations: replacement (not merge) semantics for entities, notifications, and filters, the {} vs omit distinction for filters, notification effects on future recurring email delivery, verified-recipient gating, cadence behavior, and the explicit disclosure that alerts are not covered by zero data retention.

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 core update semantics and then organizes remaining detail into distinct paragraphs (replacement rules, delivery/recipients, filters, retention). The filters paragraph duplicates the schema's filters description fairly closely, which is the main source of 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 10-parameter mutation tool with no output schema and a nested filters object, the description covers the behaviors an agent actually needs: partial-update semantics, kind constraints, replacement vs omit, error conditions (speaker_roles on ENTITY_MENTION), and the retention caveat.

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 baseline is 3, but the description adds cross-parameter semantics the schema states only per-field: keyword vs entities mutual exclusivity by alert kind, and the wholesale replacement behavior of the nested filters object including the {} clears-all case. It largely mirrors the schema's filter documentation, which caps it at 4.

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

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

States a specific verb+resource ('Update an existing alert') and immediately disambiguates the update model: only passed fields change, while entities/notifications replace wholesale. It also draws the boundary against particle_alert_create by noting an alert's kind is fixed at creation and a new alert is needed to change 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 context: use resolve tools for entity slugs, use is_active to pause/resume instead of deleting, and create a new alert to change kind. It does not explicitly route between particle_alert_get/list/preview, but the update-vs-create-vs-delete boundary is well covered.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, openWorldHint=true, and the description adds context about identical metering and plan gating. It also clarifies that all public tools are executable by name. This complements the annotations without contradicting them.

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?

Concise and logically ordered: core behavior first, then fallback rationale, then guidance to discover schemas. No redundant repetition of 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?

Strong for a dynamic dispatcher tool: it covers when to use it, how to discover target tools, and notes metering/plan gating. It lacks output format details, but given the dynamic nature and the explicit pointer to particle_catalog, 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 two parameters. The description adds meaning by explaining how to populate them: use particle_catalog for names and schemas, and pass arguments matching the target tool's input 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?

Clearly states a specific action and resource: 'Dispatch any public Particle tool by name.' It clearly differentiates itself as a compatibility fallback versus the sibling particle_* tools, explicitly saying to prefer calling discovered tools directly when the harness allows.

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 when to use the tool: as a fallback for harnesses that block calling tools not advertised on tools/list, and when not to prefer it: 'prefer calling discovered tools directly when your harness allows it.' Links to particle_catalog for discovery.

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, but the description adds substantial behavioral context: the no-args categorical menu vs. full-schema mode, the 'lean by default and EXPAND' convention, the graph/slugs-as-edges model, and the warning that JSON output is 'larger and noisier for an LLM to read.' These are non-obvious traits that materially affect how an agent uses the tool. No contradiction with annotations exists.

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

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

The description is long but rigorously structured with bold headers, bullets, and a front-loaded purpose statement. Each section—categories, expansion conventions, graph traversal, opt-in configuration, and output format guidance—earns its place because this is a meta-tool that must explain the entire ecosystem to be useful. There is no filler or redundant restatement of 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 discovery tool with no output schema, the description is remarkably complete: it covers all categories, what each invocation mode returns, how to read the menu's '↳' expand lines, how slugs connect tool responses, and how to control advertised categories via URL query parameters or headers. An agent has everything needed to call it correctly and use the results to traverse the Particle ecosystem.

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 baseline is 3, but the description adds operational meaning beyond the field descriptions: it explains that category triggers 'the FULL input schema for every tool in that category' and that markdown is the LLM-facing default while JSON is for programmatic exact extraction. It also enumerates the category options, effectively enriching the category parameter's possible values.

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 opens with a specific verb and resource: 'Browse the full Particle tool catalog.' It also clearly distinguishes itself as a meta-tool compared to the functional sibling tools, explaining that tools/list only advertises default categories while this tool discovers every callable public tool. This is far more than a tautology or vague summary.

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 explicitly says 'call this before invoking a tool you haven't seen advertised' and contrasts the advertised tools/list with the full catalog. It also explains when to use no arguments versus the category argument, and covers opt-in/exclusion mechanics via URL parameters or headers. This leaves no ambiguity about when to invoke 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 carry readOnlyHint=true, openWorldHint=true, and destructiveHint=false, lowering the bar. The description adds genuine context beyond those: the lean-default response shape, what each include section returns, the 'premium' flag on podcast_recommendations, and the cross-tool pointer that person slugs feed particle_person_get. It doesn't cover failure modes or rate limits, but for a read-only fetch with annotations present this is a strong addition.

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

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

The description is front-loaded and each sentence earns its place: purpose in sentence one, optional-section semantics in sentence two, sibling routing in sentence three. The length is proportionate to the five optional include sections it must document, with zero filler.

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

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

With no output schema, the description carries the burden of explaining return values, and it does — default payload contents (identifiers, name, description) and each optional section's contents, including the ten-podcast premium recommendation list. The only gaps are edge-case behavior (unknown slug, empty results) and what 'premium' means for the caller (billing/access implications), which are minor for a read-only fetch 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?

Schema description coverage is 100%, so the baseline is 3 — the schema already documents include, company_slug, and product_status with detailed descriptions. The description adds marginal workflow nuance ('If you already know the domain you can call this tool directly without first running particle_company_resolve') and reiterates the include options, but does not meaningfully explain anything the schema leaves out.

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 opening sentence names the verb ('Return'), the resource ('a bundled profile for one company'), and enumerates the contents (identifiers, name, description). It explicitly distinguishes itself from siblings by closing with 'use particle_company_get_podcast_ad_presence instead' for sponsor/advertising analytics, matching the highest bar for sibling differentiation.

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

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

The description gives explicit routing: use particle_company_get_podcast_ad_presence for sponsor/advertising analytics, and skip particle_company_resolve when the domain is already known ('you can call this tool directly without first running...'). It also prescribes behavior — 'The default response is lean — include only what you need' — leaving nothing about when/why to call it 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 communicate read-only and open-world behavior, so the description adds meaningful context by revealing that candidates are returned with an agent-facing identifier (slug, falling back to domain or id) and that identifiers are ANDed. This goes beyond the structured annotations, though it does not cover error or no-match 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?

Four purposeful sentences are front-loaded with the tool's purpose and return behavior, then move to input constraints and routing guidance. There is no filler or needless repetition of schema 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?

For a 6-parameter resolve tool with no output schema, the description covers required input, identifier combination behavior, output identifier shape, and downstream usage. The remaining details are fully covered by 100% schema documentation and the readOnly/openWorld annotations.

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 baseline is met. The description adds important cross-parameter semantics: at least one identifier is required even though no schema field is required, multiple identifiers are ANDed, and the returned slug/domain/id is meant to be passed as company_slug to downstream tools.

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 opens with 'Resolve a company by free-text name, ticker, SEC CIK, Wikidata QID, or domain,' naming a specific verb, resource, and accepted identifier forms. It also distinguishes itself from sibling resolve tools by directing people and non-company knowledge-graph entities to particle_entity_resolve.

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 explicitly states when to use this tool, requires at least one identifier, explains that multiple identifiers are ANDed for disambiguation, and gives a clear when-not with an alternative: use particle_entity_resolve for people or non-company entities. It even tells the agent which downstream tools should receive the returned slug.

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 read-only nature is covered. The description adds behavioral detail beyond that: it reveals that the response carries person_slug / company_slug for linked entities, and it explains that the output_format changes the serialization, noting that the JSON shape is 'larger and noisier for an LLM to read.' These are genuine behavioral disclosures not present in the annotations or schema, though it stops short of describing error conditions or response envelope.

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 in the first sentence, followed by use-case and routing guidance. The second paragraph earns its place by explaining when to prefer sibling tools and the downstream consumers of entity slugs. It is slightly longer than necessary but contains no filler; the structure flows logically from what → when → alternatives.

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 compensates by naming the returned fields (name, kind, description, Wikipedia link) and the presence of person_slug/company_slug for linked entities. It also covers the two parameters, the source of valid slugs, and the appropriate output format. For a simple read-by-slug tool, this is sufficient; an agent has enough to invoke it correctly and interpret the result, though it leaves response envelope details unspecified.

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 baseline is 3, but the description adds meaningful semantics. It clarifies that entity_slug comes from particle_entity_resolve, episode entity listings, or mention payloads, and gives concrete examples ('germany', 'bitcoin'). For output_format, it goes beyond the enum values by explaining when to use JSON ('only for programmatic chaining where exact field extraction matters') and why markdown is the default for LLM reading. This is valuable guidance the schema alone does not provide.

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 opening sentence states a specific verb and resource: this tool returns a knowledge-graph entity's profile with name, kind, description, and Wikipedia link. It explicitly distinguishes itself from sibling tools by noting it is not the full person/company profile tool and that it is for confirming slugs from particle_entity_resolve. Even without reading the schema, an agent knows exactly what this tool does and how it differs from the person/company getters.

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 explicit when-to-use guidance: 'Use it to confirm what a slug from particle_entity_resolve actually refers to' and then lists the long-tail entity categories. It also provides a clear when-not-to-use rule: for linked persons/companies, prefer particle_person_get / particle_company_get, which return full profiles. It closes with downstream usage, telling the agent that entity slugs feed mention, timeseries, and alert tools, making the tool's place in the workflow 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 the tool read-only and non-destructive, and the description adds meaningful behavioral context beyond that: candidates carry `type` and canonical `slug`, slugs feed into specific downstream parameters, and bulk queries resolve independently with `limit` applying per query. No contradictions 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 well-structured and front-loaded, with useful bullets and examples. It is slightly long due to enumerating many downstream tool/parameter names, but every sentence serves a purpose: one for definition, one for routing, one for bulk behavior.

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

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

For a two-parameter tool with no output schema, the description covers input semantics, output candidate structure, downstream usage, when to use it, and alternative tools. Nothing an agent needs to call or consume this tool 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 coverage is 100%, setting a baseline of 3. The description adds value beyond the schema by clarifying that a comma-separated `query` resolves each name independently in a single call and that `limit` applies per query, which is not explicit in the schema.

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

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

The description opens with a precise verb and resource: 'Resolve any named thing — person, company, place, or other entity — by free-text name in one union search.' It clearly distinguishes this from sibling resolve tools by stating it is a union search across entity types, and it explains the type/slug candidate structure.

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?

Excellent routing guidance: 'Use this first whenever you only have a name and don't know what kind of thing it names.' It explicitly names alternatives (`particle_person_resolve`, `particle_company_resolve`) and the conditions under which to choose them, plus bulk-resolution usage instructions.

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 this as read-only and non-destructive, but the description adds substantial behavioral context: results are ranked, the returned slug is stable and reusable across many downstream person_slug parameters, bulk queries resolve independently, and output_format changes the serialization with a warning that JSON is noisier for LLM reading. This goes well beyond what annotations could 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?

The description is front-loaded with the core action, followed by return-value semantics, then bulk usage, then alternatives. Every sentence earns its place, and the enumeration of downstream endpoints is dense but purposeful. There is no redundant phrasing.

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 resolution tool with no output schema, the description covers the essential operations: what input looks like, what output to expect (ranked candidates with slug), how bulk queries behave, and which sibling tools to use instead. An agent has enough information to both select and invoke this tool correctly in most scenarios.

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 reinforces query semantics and exposes the canonical-slug benefit, but it largely restates what the input schema already documents for limit, query, and output_format. It adds no critical parameter meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Resolve a person by free-text name' and states the concrete output ('ranked candidates with the canonical person slug'). It distinguishes this tool from sister tools by explicitly contrasting it with particle_entity_resolve and particle_company_resolve, leaving no ambiguity about its niche.

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 provides explicit when-to-use rules: use it for resolving persons, use particle_entity_resolve for organizations/places/mixed/unknown kinds, and use particle_company_resolve for companies with a known ticker or domain. It also gives bulk-query guidance, covering the main usage decisions an agent must make.

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/openWorldHint/destructiveHint, so the bar is lower, yet the description still adds substantial behavior: default page size and reverse-chronological ordering, that `limit`/`cursor` are inert in detail mode, that detail accepts up to 10 comma-separated slugs for a multi-get, and that summary returns only the first 10 mention-only lines. It also states the slug-resolution prerequisite path.

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 purpose, then modes, then workflow, then exclusions — good information hierarchy for a 14-parameter tool with three response shapes. The length is largely justified, though the three-mode behavior is restated in both the modes section and the workflow/examples, which is mildly redundant.

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

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

Covers mode selection, routing rules, required slug inputs, resolution prerequisites, pagination, and multi-get limits — everything needed to invoke correctly. No output schema exists, and the description compensates by describing the shape each mode returns, so nothing material 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 coverage is 100%, so the baseline is 3, and the description clearly beats it: it explains the mode-dependent meaning of `format`, `episode_slug`, `limit`/`cursor`, and `context_lines` beyond the schema text, plus the 'one of person_slug/company_slug/entity_slug is required' rule and slug case-insensitivity. It stops short of fully 5 because most individual parameter semantics are already carried by 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?

Opens with a precise verb+resource+scope: 'Find dialogue lines where a specific person or company is named in podcast transcripts.' It explicitly distinguishes itself from the sibling `particle_podcast_search_transcripts` (named-entity lookup vs. paraphrase-tolerant topic search), so an agent can route correctly 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?

Provides explicit when-to-use for all three `format` modes, two concrete workflow patterns (scan-then-drill-in vs. direct drill-in when the slug is already known), worked examples, and a dedicated 'When NOT to use' section naming the alternative tool. Nothing about tool selection 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 establish readOnly/openWorld/non-destructive, so the bar is lower, and the description adds real context: the default response is lean, only counts plus top entities unless `include` is used, and full transcripts are large and narrowable. It omits any note about rate limits or cost for the premium ads sibling, but the safety and payload behavior is well disclosed.

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 paragraphs, front-loaded with the payload summary before optional sections and routing alternatives. Every sentence carries information, though the middle paragraph packs six enum values into one dense sentence that slightly slows scanning.

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

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

With no output schema, the description does the work of describing the return shape (title, podcast, speakers, entities, counts) and payload sizing. It is nearly complete, but the 'related' include value and its alternative (particle_podcast_list_related_episodes) are only covered in the schema, not the prose.

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 baseline is 3, but the description goes further by explaining the rationale behind `include` (lean default vs. heavy transcript), the transcript sub-params for narrowing, and the size implications. It does not mention the 'related' enum value that the schema documents, so it is not fully additive.

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?

Opens with a concrete verb+resource ('Return a bundled overview of one podcast episode') and enumerates exactly what the bundle contains: title, podcast, speakers with entity slugs, top mentioned entities, segment/clip counts. It is clearly distinguishable from siblings like find_mentions, get_episode_ads, and list_related_episodes, which it names.

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 routing rules: use particle_podcast_find_mentions with episode_slug for 'every line about X', and particle_podcast_get_episode_ads for ad reads. It also states the default lean behavior and when to request each optional section, so an agent knows both when to call this tool and when not to.

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, non-destructive), and the description adds substantive behavior: buckets are UTC-aligned, zero-filled, Monday-aligned for weeks, ranges capped at 1000 buckets, and keyword/semantic modes add per-bucket mention counts. These constraints materially affect how an agent should call and interpret results.

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-loaded with the purpose and the routing decision before the mechanics paragraph; every sentence carries information (filters, bucket semantics, caps, exclusions). It is dense and long, but nothing is filler — the only minor cost is that a reader must hold several constraints at once.

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, and the description compensates by describing the return shape: per-bucket counts, range totals, and per-bucket mention counts in keyword/semantic modes. Combined with 100% schema coverage and annotations, an agent has everything needed to call it correctly and interpret results.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema states only locally: semantic_search requires published_after with ranges up to ~2 years, keyword vs semantic cannot be combined, and both add mention counts. It also clarifies what the at-least-one-filter rule means across the 15 params.

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

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

States a specific verb+resource ('Time-bucketed episode counts') and immediately reframes it in agent terms ('the purpose-built answer to "how often is X discussed over time"'), naming the sibling list_episodes whose filters it shares. An agent can distinguish it from particle_podcast_list_episodes, find_mentions, and search_transcripts without opening a schema.

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

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

Explicitly says to use it 'for appearance, publication, or topic trend lines instead of paging particle_podcast_list_episodes, particle_podcast_find_mentions, or particle_podcast_search_transcripts once per period' — a named alternative plus the condition that selects this tool. It also states the hard prerequisite ('at least one of podcast_slug, person_slug, ... is required') and the mutual exclusion of keyword_search and semantic_search.

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: it returns not_found for people who exist but never appeared on a podcast, and it explains the recommended_podcasts section is a pitch list with venues behind each pick. This goes beyond the annotations and helps the agent anticipate edge cases.

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 well-organized: it front-loads the core purpose, then explains optional sections, then handles the edge case. Every sentence adds information, though the include-section explanation is somewhat long and 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 profile tool with 100% schema coverage and no output schema, the description is complete. It covers the default response, optional sections, edge cases (not_found), and routing to sibling tools. An agent has everything needed to select and invoke 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%, so the schema already documents all three parameters well. The description adds value by explaining the default response (profile + lifetime stats) and clarifying that 'recommended_podcasts' is the pitch list with venues, which is not fully obvious from the schema alone. It also gives a concrete slug example and source tools for obtaining slugs.

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 returns a guest's podcast-appearance profile with lifetime stats and frequent podcasts, and explicitly distinguishes guests from people by pointing to particle_person_get for biographical profiles. It names the resource (guest), the verb (get), and the scope (podcast-appearance profile), making it easy to differentiate from siblings like particle_person_get.

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 explicit guidance on when to use this tool vs alternatives: use particle_person_get for people who exist but have never appeared on a podcast, and the same slug works with particle_person_get for biographical profiles. It also explains optional include sections and their purposes, so an agent knows exactly what to request.

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, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds real behavioral detail beyond that: cursor is not supported for mode=movers, 'slots' ignores other filters, and each row carries the matched podcast_slug for chaining. It stops short of describing pagination limits or result sizing, so not 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?

Front-loaded with the four modes as bullets, then a short note on podcast_slug propagation and the sibling alternative. Efficient and scannable, though the mode bullets are long enough that a reader must parse carefully; not maximally tight.

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 12-parameter, no-required-args, no-output-schema tool, the description covers mode semantics, defaults (apple, us, limit 25, window 1), filter behavior, and the chaining field returned in rows. Nothing an agent needs to select and invoke a mode correctly 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. The description goes further by explaining cross-parameter interaction (podcast_slug flips chart/history into per-podcast queries; source narrows the slots listing), which the schema descriptions state only in isolation. That added mode-interaction meaning justifies a 4.

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 opening states a specific verb and resource ('Podcast chart rankings from Apple Podcasts and Spotify') and then enumerates four distinct modes with concrete semantics for each. It also distinguishes itself from the sibling particle_podcast_resolve by naming the exact alternative call for at-a-glance chart presence.

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?

Each mode is given an explicit use case ('slots' to discover filter values, 'movers' for rank changes over window_days), and the description explicitly routes single-podcast lookups to particle_podcast_resolve with include: ["rankings"] as a one-call alternative. When-and-when-not guidance is concrete rather than 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 (readOnlyHint, destructiveHint=false, openWorldHint), so the description goes further by explaining ranking behavior, the detail-vs-list mode switch, and output_format trade-offs (JSON 'larger and noisier for an LLM'). It stops short of describing pagination semantics beyond the cursor parameter.

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 front-loaded paragraphs that each carry distinct information — catalog browsing, detail mode, and the sibling alternative. Slightly long, but no sentence is redundant, and the key routing decision is stated early.

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 10-parameter filter/list tool with annotations and no output schema, the description covers the filter dimensions, the detail mode, the output format choice, and the alternative tool. Nothing an agent needs to call it correctly 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 coverage is 100%, which sets the baseline at 3, but the description adds genuine meaning: speaker takes a person slug and returns only that person talking, clip_id fetches full detail, include=transcript attaches dialogue, and min_engagement above 70 is 'typical for a strong clip'.

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 ('Browse AI-extracted highlight clips across the catalog, ranked by engagement potential') and names the enumeration of filter dimensions. It clearly distinguishes itself from the transcript-search sibling, so an agent can tell them apart without opening a schema.

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

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

Explicitly routes the agent: text/topic-based discovery should use particle_podcast_search_transcripts instead, and clip_id switches the tool into single-clip detail mode. It also names the handoff to particle_podcast_get_episode via episode slugs.

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 cover the safety profile (readOnly, openWorld, non-destructive), and the description adds genuine behavioral context the annotations do not: the default scope is ingested episodes only, and reaching a show's back catalogue requires passing transcript_status together with podcast_slug. It also warns that requestable episodes have no transcript, segments, speakers or entities until requested. A clear step above the annotated 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?

Three short paragraphs, front-loaded with purpose and filters, then the default-vs-back-catalogue caveat, then routing to siblings. Every sentence carries weight, though the middle paragraph is dense enough that it could be marginally tighter.

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 15-param, zero-required, no-output-schema list tool the description covers scope, defaults, filter surface and sibling routing adequately. It does not describe pagination/cursor semantics beyond the schema, but the schema documents those fields, so the gap 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 baseline is 3, but the description adds meaning beyond the schema by explaining the interaction between transcript_status and podcast_slug (default vs. back-catalogue behaviour) and flagging the requestable state's downstream effects. That is real semantic value over the per-parameter text.

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

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

States a specific verb+resource ('List episodes across the catalog') and enumerates the filter dimensions, so an agent knows exactly what it returns. It also explicitly names the sibling tools it is not (find_mentions, search_transcripts), distinguishing it from the rest of the podcast_* family.

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

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

Gives explicit when-to-use ('episode-level discovery when you only need metadata') plus two named alternatives with their governing conditions ('for dialogue around a person... use find_mentions' / 'for ranked retrieval by topic... use search_transcripts'). Nothing 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 cover safety (readOnlyHint, destructiveHint false), so the bar is lower, yet the description still discloses substantive behavioral traits: the trends-mode enforcement rules (distinct podcasts, 5+ min identified speaking, mononymous exclusion, 2x spike threshold) and the pagination/output_format tradeoffs. This is unusually rich disclosure.

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-loaded with the mode split and dense with information; nearly every clause earns its place. Slightly verbose in places (e.g. 'two opinionated modes', the long list of trends-mode constraints) but not padded.

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 browse tool with no output schema, the description covers modes, parameter precedence, pagination and output format, and routing to follow-up tools. It does not describe the shape of returned guest entries (fields, ordering metadata), a minor gap given the absence of an output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by stating parameter interaction rules not present in the schema ('ignored when podcast_slug is set', 'only valid with the default directory mode') and guidance on when to use json vs markdown. It stops short of explaining cursor/limit behavior 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+resource (browse podcast guests) and immediately splits it into two named, well-defined modes with distinct ranking semantics. It also names the downstream tools (particle_podcast_get_guest, particle_person_get) so the agent can place this tool in the workflow.

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 describes when each mode applies ('directory' for lifetime-ranked directory vs 'trends' for cross-show press tours) and when the slug parameters take effect, including the precedence rule ('topic_slug ignored when podcast_slug is set', podcast_slug only valid in directory mode). It also tells the agent what to do with the returned guest slugs.

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, destructiveHint=false, and openWorldHint=true, so the safety profile is clear. The description adds substantial behavioral context beyond annotations: precomputed related sets, language restriction, relatedness floor, exclusion of machine-generated/farmed feeds, deduplication of publisher duplicates, the meaning of an empty first page via coverage, and cursor behavior at the end of the list. 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 long but tightly structured and front-loaded: main purpose first, then result contents and include semantics, then precomputation/empty-page mechanics, then explicit sibling routing. Every paragraph earns its place, with no filler or repetition.

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

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

For a complex 11-parameter read-only tool with no output schema, the description supplies the missing context an agent needs: result shape (slug, score, band), score interpretation (prefer band over min_score), include behavior, pagination edge cases, data provenance, and how returned slugs chain into sibling tools. Nothing essential is left ambiguous.

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 all 11 parameters thoroughly. The description adds practical meaning beyond the schema for include ('basis' used to explain a recommendation or keep only pairs related for a chosen reason) and for output_format's intended use, but it does not add syntax or constraints for every parameter. Baseline is 3 when schema does the heavy lifting; the extra usage-oriented guidance for include justifies a 4.

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 the shows most related to a podcast, best first') and immediately distinguishes itself from siblings by naming topic browsing, guest lookup, and advertiser co-occurrence as different tools. An agent can tell exactly what this tool does and does not do without opening a schema.

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

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

Provides explicit when-to-use guidance ('Add include: ["basis"] to see WHY'), when-not-to-use alternatives ('Not a topic browser... Not a guest lookup... Not advertiser co-occurrence'), and a routing shortcut ('For the five most related shows inline on a resolve, pass include: ["related"] ... instead of calling this tool'). It also explains empty-first-page semantics, which is critical for correct interpretation.

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 only cover the safety profile (readOnly, openWorld, non-destructive), yet the description discloses non-obvious behaviors: a per-show cap of two episodes, deduplication of republished content, exclusion of machine-made/syndication feeds, a calibrated score with a strong/moderate/weak band, and provenance fan-out via episode and podcast slugs.

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-loaded with the core definition and organized into definition, usage, and exclusions, with no filler sentences. It is on the long side (three dense paragraphs) but each sentence carries operational information rather than restating the name or 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?

With no output schema, the description still tells the agent what each row carries (score, band, slugs), how to expose the basis signals, and how results are deduplicated and capped, plus how pagination params behave. Nothing needed to call it correctly 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 coverage is 100%, so baseline is 3, but the description adds real meaning beyond the schema: published_within_days is framed as 'same news cycle' with a 7–30 recommendation, same_podcast is explained as admitting the show's own episodes (otherwise excluded), and include:['basis'] is tied to the signals returned per row.

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

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

States a specific verb+resource+scope: 'Episodes from OTHER shows that cover the same story or subject as a given episode.' It names the sibling tools it is not (search_transcripts, find_mentions) and explains the ranking basis, so an agent can distinguish it from every related sibling without opening a schema.

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

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

Explicit when-to-use ('when you already have an episode and want its coverage elsewhere') plus explicit when-not ('Do NOT use it to find dialogue about a topic... nor to find every line naming an entity') with the correct alternative named for each. It also documents the same_podcast and published_within_days switches that change the intended usage.

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=true, openWorld=true, destructive=false, so the bar is met; the description adds genuinely useful context beyond that: free-text matching is forgiving (typos, extra words), results are best-match-ordered, text matches carry match_quality, an empty list means no plausible candidate, and premium hydrations require a plan with premium endpoints. It also notes hydrations are off by default.

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-loaded with the purpose and routing before the detail, and the bulleted include section is scannable. It is long and substantially restates the schema's include descriptions, so it is slightly verbose rather than maximally tight.

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 burden of explaining return values (slug, title, episode count, bias, top recurring speakers with entity slugs) and it does so. For a 10-parameter, zero-required resolver with an enum of hydrations, the description is complete enough to call 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 baseline is 3. The description adds semantic value above the schema: it explains the empty-list/ordering semantics, the match_quality field, and explicit cross-references between included data and the sibling tools that extend it (e.g. rankings vs particle_podcast_get_rankings, related vs particle_podcast_list_related).

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

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

The description states a specific verb+resource ('Find a podcast') and enumerates the exact resolution keys (free-text title, slug, iTunes ID, RSS URL). It also names the sibling tools that consume the returned slug, so an agent can distinguish this resolver from the downstream consumers without opening any 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?

It explicitly routes the agent: use the returned slug as the handle to feed into particle_podcast_find_mentions, particle_podcast_list_episodes, and particle_podcast_get_sponsors. It also states the no-identifier fallback (most recently updated podcasts) and the filter alternatives (topic_slug, suitability_tier, min_popularity), plus cross-references particle_podcast_get_rankings for movers/history.

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 read-only/non-destructive profile, but the description adds substantial behavioral context beyond them: segment partitioning semantics, the absence of a separate clip-search tool, how errors name the offending parameter and suggested retry, and the size/latency tradeoff of compact mode.

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-loaded with purpose and organized under bold headers, which suits a 20-parameter tool. It is, however, verbose and mildly redundant — the clip-search explanation is stated twice and some parameter guidance is repeated in prose after the schema already covers it.

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 20-param tool with no output schema, the description covers the necessary ground: it explains what each result contains (segment, windows, overlapping clips), the response-shape options, and the pagination/error behavior. An agent has enough context to call it correctly without inference.

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?

With 100% schema coverage the baseline is 3, but the description adds practical meaning beyond the schema: 'do not put a name in semantic_search', the 'ranked' relaxation for keyword_match, and the role-omission guidance. Much of this also appears in the schema descriptions, so it is additive rather than transformative.

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 (search) and resource (podcast transcripts/dialogue) with the three query modes named inline (semantic, keyword, hybrid). It explicitly differentiates from siblings, naming `particle_podcast_find_mentions` and `particle_podcast_get_episode` for the adjacent tasks an agent might confuse it with.

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

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

Gives explicit when-to-use vs. alternatives ('find dialogue about a topic' vs. 'every line naming a person' → find_mentions), a start-broad-then-narrow workflow, the screening pattern with `format: 'compact'`, and query-construction rules for semantic vs. keyword. Exclusions and alternatives are both 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 annotations already signal a safe, read-only operation. The description adds useful behavioral context beyond that: hierarchical traversal semantics, the parent/child slug convention, and the fact that results are direct children only. It does not mention pagination details or rate limits, but those are less critical given the read-only annotation and schema-covered parameters.

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 three sentences, front-loaded with the main verb and resource, then immediately explains the key branching behavior and slug convention. Every sentence earns its place with no redundancy or filler.

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

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

For a read-only taxonomy browser with all parameters optional and fully described in the schema, the description covers the core behavior and the one non-obvious detail (slug convention). It could optionally mention that deeper traversal is done by passing a child slug as parent_slug, but this is strongly implied and the tool is otherwise complete enough for correct invocation.

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 baseline is 3. The description adds meaningful parameter nuance by explaining the parent/child slug convention and how omitting parent_slug changes the result set, which goes beyond the raw schema descriptions and helps agents construct correct calls.

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 exactly what the tool does: it navigates the topic taxonomy, returning top-level roots when parent_slug is omitted and direct children when it is provided. The parent/child slug convention and example make the tool easily distinguishable from the alert, company, podcast, and other 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 clearly explains the two main usage modes (browse roots vs. children of a topic) and frames the tool as a way to find well-named categories. It does not explicitly name alternative tools for similar tasks, but the intended use case is clear and no exclusionary guidance is needed.

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