particle-pro

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

Goes well beyond the readOnlyHint=false / destructiveHint=true annotations: discloses the possible credit-to-paid billing transition and the need for explicit user confirmation, that paused alerts avoid it, that creation backfills the past week without emailing, that unverified recipients stay silent, and that alerts are excluded from zero data retention. These are exactly the operational facts an agent cannot infer from structured fields.

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 rightly dense on billing/backfill, but the long filters paragraph duplicates what the schema already documents in greater depth (language tag collapsing, popularity percentile, statement characteristics), padding a description that is already the longest part of the definition.

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, nested-object mutation with no output schema, the description covers everything an agent needs: the resolve-then-create prerequisite chain, kind selection, billing consent, backfill behaviour, recipient verification, DZR status, and which sibling tools consume the returned alert id. Nothing material is left to 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?

Schema coverage is 100%, so the baseline is 3; the description still adds cross-parameter meaning the schema only states piecemeal — that is_active=false sidesteps the billing transition, that entities and keyword are mutually exclusive by kind, and the coupling of keyword with the free-text description field for disambiguation. It restates the filters axes, but the workflow-level framing is genuine added value.

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 ('Create an alert that watches a single entity and sets up recurring email delivery') and enumerates the three signal kinds with what each fires on. It explicitly distinguishes itself from particle_alert_preview and the resolve tools, so an agent can place it in the workflow without reading the schema.

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

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

Gives explicit routing rules: resolve a name first with particle_entity_resolve and pass the slug; use KEYWORD_MENTION when no slug exists or the entity lacks podcast coverage; call once per entity to cover several; use particle_alert_preview before committing. It also states when-not (paused alerts avoid billing, speaker_roles on ENTITY_MENTION errors).

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 destructiveHint=true, but the description adds genuinely new behavior: this is a soft delete, matches and deliveries are retained for audit, the alert disappears from particle_alert_list, and unauthorized callers get a 403. The note that an API key acts as the user who created the key is context the annotations cannot express.

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-loaded with the core action and the soft-delete consequence, followed by the alternative and the permission rule. Every sentence carries information an agent needs; there is no filler.

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

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

For a single-parameter destructive tool with no output schema, the definition covers what is destroyed versus retained, where the alert disappears from, the escape hatch for pausing, and the authorization model including the 403 outcome. 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?

There is a single parameter with 100% schema description coverage, so the schema already carries the parameter documentation and the description need not repeat it. The description implies the alert must be one the caller owns or administers, but adds no format or identifier guidance for alert_id itself, matching the baseline of 3 when the schema does the heavy lifting.

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

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

The description opens with a specific verb+resource ('Delete an alert') and immediately qualifies the scope with the soft-delete semantics, so an agent knows exactly what operation is performed. It also names the sibling tool it is not (particle_alert_update), which is the main source of ambiguity among the alert 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?

It gives an explicit when-not and the alternative: 'To pause an alert instead of removing it, use particle_alert_update with is_active=false.' It also states the caller conditions under which the tool is valid, so an agent can decide before invoking.

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 read-only, non-destructive, closed-world safety profile, so the description only needs to add behavioral nuance — which it does: filters is omitted when empty, markdown is the default output, and json is described as larger and noisier for an LLM. It doesn't discuss pagination limits or error behavior for a missing alert_id, but the added context is substantive.

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 sentences, front-loaded with what is returned, then conditional behavior, then the routing alternative. Every sentence carries distinct information with no filler.

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

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

No output schema exists, so the description compensates by enumerating the returned fields and explicitly stating that filters is omitted when absent. Combined with the include-based optional sections and the sibling pointer, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds genuine meaning beyond the schema: the match_limit default/behavior when include=matches, the conditional relationship between include and match_limit, and the practical tradeoff of output_format='json' ('noisier for an LLM to read').

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 (fetch) and resource (a single alert's full configuration) and enumerates the concrete fields returned (title, kind, cadence, watched entities, notification emails, filters). It also names the sibling particle_alert_list_matches, so the agent can distinguish a single-alert fetch from a paginated history query.

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 default behavior ('response is just the configuration'), the opt-in paths with their exact parameter values (include=['matches'], include=['deliveries']), and the alternative tool with its selection condition ('for the full, paginated match history with transcript excerpts, use particle_alert_list_matches'). This is the when/when-not/alternative pattern.

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=true, destructiveHint=false), so the bar is lower, and the description adds the sort order and the fact that entries carry an id. It doesn't mention pagination behavior (cursor round-trip) or rate limits, which would raise this further.

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

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

Two sentences, zero filler, and the identification of the tool is front-loaded before the sibling routing guidance. Every clause earns its place.

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

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

With no output schema, the description usefully discloses the ordering and that each entry includes an id, which is what an agent needs to chain calls. It stops short of describing the remaining entry fields (e.g., name, status), so it is strong but not exhaustive.

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 limit, cursor, and output_format are already fully documented in the schema. The description adds no syntax, format, or default information beyond that, leaving this at 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?

States a specific verb and resource ('List the alerts in your project') plus a scope-defining detail (newest first). It also distinguishes itself from four named siblings by describing what each one does with the id this tool returns.

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

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

Explicitly routes the agent to the correct follow-up tool for each intent: particle_alert_get for configuration, particle_alert_list_matches for activity, update/delete for management. An agent can pick the right tool without opening sibling schemas.

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 a safe read (readOnlyHint true, destructiveHint false), so the bar is lower, yet the description still adds real behavior: results are newest-first, and backfilled matches from the creation sweep are flagged and never sent an email. It omits pagination behavior, but the substantive disclosure here is well beyond the annotations.

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

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

Four sentences, front-loaded with the verb and the highest-value behavioral fact (the payoff + newest-first). Every sentence carries information; the phrasing "the payoff of an alert" is slightly decorative but not wasteful, keeping it just short of 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?

With no output schema, the description carries the return-value burden and does so: it explains that each match names the watched entity and the episode/podcast slugs, plus what detailed view adds and how backfilled matches appear. Combined with a fully-covered input schema and read-only annotations, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so view, after, before, limit, cursor, and output_format are all documented structurally; the description largely restates the view/after/before semantics. The only marginal addition is that episode/podcast slugs feed particle_podcast_get_episode and particle_podcast_resolve, which justifies baseline 3 rather than higher.

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 matches an alert has caught") plus ordering ("newest first") and even characterizes the payoff ("the payoff of an alert"). Combined with the name and the explicit downstream-tool references, an agent can distinguish this from particle_alert_list without opening the schema.

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

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

Gives concrete usage cues: use view=detailed for transcript excerpts, use after/before to scope a date range, and notes which sibling tools the returned slugs feed. It stops short of explicitly saying when not to use it or contrasting it with particle_alert_list, so it's clear context rather than full when/when-not routing.

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

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

Adds meaningful behavior beyond the annotations: it is asynchronous ('Starts a background sweep and caches its progress and results'), it does not create an alert or notify anyone, and relevance=RELEVANT makes the count an upper bound. That last point is genuinely load-bearing for interpreting the number returned. It stops short of covering cost/latency or what happens on repeated calls, so it is not a full 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 core purpose and the create-follow-up in the first three sentences, with per-parameter caveats after. It is on the long side and restates some schema content (the narrowing-versus-projection detail appears both here and in the filters schema), so a little trimming is possible 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?

With no output schema, the description carries the return-value burden and does so: total match count, per-day breakdown, and a sample of recent matches with episode context. Combined with the async/caching disclosure and the create-then-verify workflow, an agent has enough to call it and interpret the result 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, but the description adds a non-obvious semantic distinction the schema only partially states: languages and speaker_roles narrow the sweep while relevance and source_popularity are read-time projections that do not, making the count an upper bound under relevance=RELEVANT. It also flags the window default/max in prose, though much of the per-parameter guidance duplicates the already detailed 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 specific verb-plus-resource and an explicit temporal qualifier: 'Preview how often an alert would fire BEFORE creating it.' It then enumerates exactly what the sweep returns (total count, per-day breakdown, recent-match sample with episode context), which an agent cannot confuse with particle_alert_create or 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?

States the two concrete use cases ('size an alert (REALTIME vs DAILY vs WEEKLY cadence)' or 'confirm the entity slug watches the right thing') and names the follow-up sibling: 'then call particle_alert_create with the same entity slug'. It also instructs passing the same filters so the estimate matches the saved alert, and explicitly scopes the tool out of creating alerts or sending notifications.

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 flag this as destructive, non-read-only and open-world, and the description adds real context beyond them: wholesale replacement of entities/notifications, the fact that filter objects replace rather than merge, ZDR exclusion, kind-dependent unprocessable_entity errors, and email verification gating. However, it never states what the response looks like or whether the caller can see prior values before overwriting a set — gaps that matter for a destructiveHint mutation.

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?

Well front-loaded, but long and partly redundant: the filters paragraph restates the speaker_roles / speaker_statement_characteristics restrictions that already appear verbatim in the schema descriptions. The delivery/verification paragraph repeats the `notifications` param description. Tightening would preserve meaning with less duplication.

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 the tricky parts an agent needs for a 10-param destructive mutation with nested objects: replacement semantics, kind constraints, pause semantics, filter clearing, and error conditions. Missing only the return shape (no output schema exists) and whether alert_id is org-scoped, which keeps it from a 5.

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 already 100%, so the baseline is 3; the description earns extra credit by adding cross-parameter semantics the schema cannot express — keyword vs entities mutual exclusivity by alert kind, {} clearing filters, and is_active meaning pause/resume rather than delete. It does repeat a fair amount of the schema's own enum/filter prose, which caps it below 5.

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 specific verb+resource ('Update an existing alert') and immediately clarifies the lifecycle boundary against particle_alert_create ('an alert's kind is fixed at creation — to change it, create a new alert'). An agent can distinguish update from create/delete/get/list without consulting 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?

Explicitly states partial-update semantics ('Only the fields you pass change'), which params replace wholesale, and the kind-specific rule that KEYWORD_MENTION takes `keyword` while entity alerts take `entities`. It also routes the agent to particle_alert_create for kind changes and names resolve tools for 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 declare readOnlyHint=false, destructiveHint=true and openWorldHint=true, and the description does not contradict them. It adds context the annotations cannot express: that metering and plan gating apply identically to direct calls, and that client tool lists go stale after a deploy. It stops short of noting that the destructive/read-only profile is inherited from the target tool, which would be the natural next clarification.

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 purpose, then the fallback rationale, then the discovery pointer and the stale-list instruction. Efficient overall, though the opening sentence and 'every public Particle tool is executable by name' partially restate each other.

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 nested-argument dispatcher with no output schema, the description covers how to find valid tool names and schemas, what billing/gating applies, and the stale-catalog edge case. The one unstated piece is that the response mirrors the target tool's own output, which an agent could reasonably wonder about.

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 properties are documented, including an example name and the instruction that 'arguments' must match the target tool's input schema. The description reinforces the discovery path via particle_catalog but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Dispatch any public Particle tool by name.' The description immediately positions it as a compatibility fallback rather than a normal tool, which cleanly distinguishes it from the concrete siblings like particle_podcast_get_episode and from the discovery sibling particle_catalog.

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 ('harnesses that block calling tools that weren't advertised on tools/list'), when-not ('prefer calling discovered tools directly when your harness allows it'), the discovery alternative ('Use particle_catalog to discover tool names and input schemas'), and an explicit instruction on the stale-list case ('never report it unavailable'). 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 already declare readOnly/non-destructive/closed-world, yet the description still adds substantial behavior: discovery is free while execution is metered and plan-gated, and the catalog payload carries the `↳` expand-option line. It could go one step further on how large the no-argument menu response is, but the cost and response-shape context is well 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 leading paragraph front-loads the core insight (unadvertised tools are callable) before any detail, and the two convention bullets genuinely earn their space. The full category enumeration is somewhat redundant since the tool itself returns that menu, which costs it a point.

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, zero-required discovery tool with annotations covering the safety profile, the description covers what both modes return, the metering model, and the traversal model an agent needs to use the catalog effectively. Nothing about calling 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% and both parameter descriptions already cover the category-vs-menu behavior and the markdown/json tradeoff, so the schema carries this dimension. The description's added detail is really cross-catalog convention (include arrays, mode/format switches) rather than meaning for these two parameters, which is helpful context but not parameter semantics.

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

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

States a specific verb and resource ('Browse the full Particle tool catalog') and immediately explains the distinguishing premise: tools/list is incomplete, but every public tool is callable by name. It differentiates itself from the sibling meta-tool particle_call by being the discovery half of that pair.

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 branching on when to call with no arguments (categorical menu) vs with `category` (full input schemas), plus the derived rule 'call this before invoking a tool you haven't seen advertised.' It also names the alternatives for getting the same information (?include=, ?exclude=, ?tools= URL params), so the agent can choose the right path.

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, non-destructive, open-world), and the description adds useful context: the default response is lean and sections are opt-in, with a note that person slugs feed particle_person_get. Doesn't discuss rate limits, auth, or premium gating beyond the schema, so slightly short of 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?

Two tight paragraphs, front-loaded with the default response shape, then the include options, then routing to the alternative. Slightly dense but every sentence carries weight.

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 fetch with full schema coverage and no output schema, the description fully explains what returns by default, how to expand it, and where to go for adjacent data. 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 already 100%, so baseline is 3; the description elevates by explaining the relationships between parameters — that `include` sections chain into particle_person_get and that `product_status` filters include=products. Minor gap: doesn't restate the product_status lifecycle values, but the schema does.

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 (Return) and resource (bundled profile for one company), enumerating exactly what fields come back (slug, ticker, domain, CIK, QID, name, description). Explicitly distinguishes itself from particle_company_get_podcast_ad_presence for ad analytics.

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-the-alternative guidance ('For sponsor/advertising analytics... use particle_company_get_podcast_ad_presence instead'), notes it can be called directly with a domain without first running particle_company_resolve, and advises 'request only what you need.'

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?

Beyond the readOnly/openWorld annotations, it discloses the default window (last year, weekly/monthly buckets), what population is counted (current roles only unless include_past_roles), that shares are of scored lines with short lines excluded, and that `low_sample` flags fewer than 20 underlying lines. Those sampling caveats are exactly the kind of trait an agent needs to interpret the numbers honestly.

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 purpose and example queries are front-loaded, and the two follow-up paragraphs cover population and caveats rather than restating the name. It is dense and long for a tool description — the examples paragraph could be trimmed — but nearly every sentence carries usable information.

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

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

For a 7-parameter analytical tool with no output schema, the description explains what the payload contains (shares per bucket per interval, speaker counts, low_sample flags) and how to enrich it with examples. It stops short of describing the response's structural shape, but the default markdown rendering and schema docs cover most of 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?

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining that include=['examples'] returns a strongest line per bucket with a `person_slug` usable in the person sibling, plus an episode and a playable link. It also clarifies the population semantics tied to include_past_roles, though it doesn't touch interval or output_format beyond what the schema already says.

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 framing — 'how a company's people speak on podcasts' broken into negativity, hedging, vagueness, and time orientation — and immediately names the exact metrics returned. It distinguishes itself sharply from the sibling `particle_person_get_statement_characteristics` by scoping to a whole company's people rather than one person.

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 concrete trigger questions ('how confident do OpenAI's people sound lately', 'are Microsoft's executives talking more about the future'), names the single-person alternative, and states the prerequisite of resolving the company first with `particle_company_resolve`. Both the when-to-use and the when-not-to-use path are explicit.

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, openWorldHint, destructiveHint=false), so the bar is lower. The description still adds real context beyond them: the call returns multiple candidates and the identifier to carry forward (`slug`, with `domain`/`id` fallback). It does not discuss candidate ranking, ambiguity handling, or rate limits, which keeps it short of 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-loads the input forms and the return contract in the first sentence, then uses a short second paragraph for the AND-composition rule and the sibling redirect. No filler or restatement of the parameter list.

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

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

With no output schema, the description carries the return-value burden and does so by naming the candidate payload and the field to forward. Combined with the requiredness and ANDing rules, an agent has everything needed to call this tool and chain its result 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, but the description contributes two facts the schema does not encode: that at least one identifier is mandatory (the schema lists zero required parameters) and that multiple identifiers are ANDed rather than ORed. These meaningfully change how an agent composes a call.

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

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

States a specific verb (resolve) and resource (company) plus the exact accepted identifier forms (name, ticker, CIK, QID, domain). It also distinguishes itself from the adjacent resolvers by explicitly routing people/other KG entities to `particle_entity_resolve`, so an agent can pick it 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?

Gives a hard precondition ('At least one identifier is required'), tells the agent identifiers are ANDed for disambiguation, and names the alternative sibling (`particle_entity_resolve`) for non-company entities. It even lists which downstream tools consume the returned identifier, which is actionable routing guidance.

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

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

With readOnlyHint/destructiveHint already covering the safety profile, the description adds valuable payload context: the response carries person_slug/company_slug when the entity is linked, which is behavior the annotations do not convey. It stops short of describing pagination or error behavior, but for a read-only lookup this is a solid addition.

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

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

Purpose and field list are front-loaded in the first clause, followed by the disambiguating condition and then downstream wiring. Every sentence carries distinct information with no filler.

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

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

For a two-parameter, read-only lookup with no output schema, the description covers what is returned, when to prefer it, when to prefer siblings, and where its slug input and output connect. 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%, and both parameters (entity_slug, output_format) are fully documented in the schema, so this is baseline. The description adds provenance for entity_slug (from particle_entity_resolve, episode listings, mention payloads) but no additional format or syntax detail beyond what the schema already 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?

States a specific verb and resource ('One knowledge-graph entity's profile') and enumerates the fields returned (name, kind, description, Wikipedia link). It distinguishes itself from siblings by naming particle_person_get/particle_company_get as the preferred tools for linked persons and companies.

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 ('confirm what a slug from particle_entity_resolve actually refers to') and identifies its niche ('the long tail that isn't a person or company'). It names the alternatives and the condition that selects them, plus the downstream tools whose input it feeds.

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/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral value: each candidate carries a `type` and canonical `slug`, and it maps each type's slug to the downstream parameters that consume it, which is more than the annotations 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?

Front-loaded with the core purpose, then a scannable type-to-slug bullet list and a bulk-resolution note. Slightly long, but nearly every sentence carries routing information an agent needs, so there is little waste.

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 annotations covering safety and no output schema to worry about, the description supplies the missing return-shape context (candidates carry `type` and canonical `slug`) and how to consume those slugs downstream. Nothing an agent needs to call it correctly is absent.

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

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

Schema coverage is 100%, so both `query` and `limit` are already fully documented, including comma-separated bulk semantics and per-query grouping. The description largely repeats that and only marginally adds the per-query behavior of `limit`, so baseline 3 applies.

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

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

States a specific verb ("resolve") and resource ("any named thing — person, company, place, or other entity") in one union search, and explicitly distinguishes itself from particle_person_resolve and particle_company_resolve. An agent can select this tool 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?

Gives an explicit routing rule ("Use this first whenever you only have a name and don't know what kind of thing it names") plus the conditions selecting the alternatives: person_resolve when the type is known, company_resolve when ticker/domain/CIK/QID are known. Bulk-query usage is also spelled out.

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

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

Annotations only cover the read-only/open-world safety profile, and the description adds substantial operational context: the default vs. opt-in section behavior, the 30-day default window capped at 90 days, how standing filters ranking, and the markdown-vs-json tradeoff ('JSON shape is larger and noisier for an LLM to read').

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

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

Front-loaded with the core purpose, then routing, then alternatives — each paragraph carries distinct information and nothing is filler. It is dense with parentheticals and slightly long, but 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 10-param, no-output-schema tool, the description covers defaults, constraints, opt-in return contents ('with appearances, shows and last appearance'), and disambiguation from four sibling tools. An agent has everything needed to call it correctly without opening the schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description still adds real meaning on top of the schema, e.g. min_podcasts 'raise it to favor guests booked across the medium over a show's regulars' and the window cap semantics. It stops short of exhaustively explaining every param, but the value-add is genuine.

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 ('Describe one occupation or field of research') plus what the default response contains (parent, children, crosswalk) and what opt-in sections add. It is immediately distinguishable from siblings like particle_expertise_resolve (which produces codes) and particle_person_get (which consumes slugs).

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: take codes from particle_expertise_resolve, retry on unresolved_reference/not_found, use particle_podcast_list_guests for multi-criteria guest search, and particle_podcast_resolve with include:['guest_expertise'] for one show's guest mix. It even names the exact invocation pattern for a common query ('the shows that book established finance experts').

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?

Beyond the read-only/non-destructive annotations, the description discloses the code systems in use (SOC 2018, ISCO-08, ANZSRC 2020), the returned fields per code, hierarchy traversal behavior, and the fallback to capacities such as `executive_founder`. This is substantial behavioral context for a resolver tool with no output schema.

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

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

The purpose and usage guidance are front-loaded, and the dense content is largely relevant for a complex resolver. It is long and includes a lengthy cross-tool parameter list, but almost every sentence carries actionable information.

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

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

There is no output schema, but the description explains the return structure at a useful level: each code comes with slug, level, parent, and the parameters that accept it. Combined with the annotations and the detailed schema, an agent has enough information to select, call, and chain 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 already 100%, so parameter documentation is strong. The description still adds useful semantics beyond the schema, especially for `parent`: walking the SOC/ANZSRC hierarchy one level down, and the fact that a group or everyday name filters everything below it.

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: 'Turn free text into the occupation and field-of-research codes the speaker-expertise filters take.' It explicitly distinguishes this resolver from person/company/entity resolvers and from the topic taxonomy, so an agent can identify its role without opening the schema.

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

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

It gives clear when-to-use guidance: questions that restrict speakers by occupation, profession, credentials or industry. It also explains when this tool is optional, when to retry after an `unresolved_reference`, and names the sibling resolvers to use instead for people, companies, or entities.

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 safety is covered. The description adds genuinely useful behavior beyond that: the default payload is lean, sections are opt-in, `output_format='json'` is larger/noisier and meant for programmatic chaining, and it flags that only the current team reliably indicates where a player is today whereas a team with no end year may have been left.

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 core purpose and slug provenance are front-loaded in the first sentence, and the closing sentence routes analytics cleanly. The middle paragraph is a dense wall of text with run-on clauses (notably the 'sports' enumeration) and partially repeats the schema's `include` documentation, so it is informative but 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?

With no output schema, the description carries the burden of describing returns and does so section-by-section, plus documents the lean default and serialization choice. It omits error/invalid-slug behavior and any rate or permission notes, but an agent has enough to 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 description coverage is 100%, so the baseline is 3. The description goes further by enumerating what each `include` value yields and cross-referencing downstream consumers (episode/podcast slugs for follow-up calls, entity slugs for `particle_entity_get`, occupation/field codes accepted by `guest_occupation`/`guest_field` and `particle_expertise_get`), though much of this overlaps the schema's own enum description.

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

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

The description states a concrete verb and resource ('Return a person's profile: name, current role, and bio') and pins the keying input to the canonical slug from `particle_person_resolve`. It also distinguishes adjacent capabilities by routing analytics to `particle_podcast_get_guest` and entity lookups to `particle_entity_get`, so an agent can separate it from siblings without opening schemas.

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 clear routing: obtain the slug via `particle_person_resolve`, use `particle_podcast_get_guest` for guest analytics, and request only the `include` sections needed since the default response is lean. There are no explicit when-not-to-use conditions (e.g. when a resolve-only answer suffices), but the context for correct use is strong.

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?

Beyond the readOnly/openWorld annotations, it discloses the scoring basis (shares are of the person's scored lines; too-short lines carry no characteristics), the low_sample flag threshold of 20, the default one-year window, and exactly what include=['examples'] adds, including episode slugs and a playback link.

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 semantic meaning of the output, then mechanics, then routing to alternatives. Dense but mostly earns its space; the second paragraph packs several unrelated points (scoring caveat, alternative tool, resolve prerequisite) rather than sequencing them cleanly.

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

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

With no output schema, the description carries the return-shape burden and does so: it enumerates the bucket dimensions, the overall vs per-interval breakdown, the low_sample marker, and the structure of the optional examples section. An agent can call this correctly without further documentation.

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 already 100%, so the baseline is 3; the description earns extra by explaining why to add include=['examples'] and how its output chains into particle_podcast_get_episode. It also restates the default window behavior, though interval/output_format semantics are largely left to the schema.

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

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

The description names a specific resource and scope: how a person speaks on podcasts, broken into sentiment, hedging, vagueness and temporal-orientation buckets, overall and per week/month. It is clearly distinguishable from siblings such as particle_podcast_get_episode_timeseries or particle_person_get, and it explicitly is not the transcript-search tool.

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 concrete trigger questions ('is Sam Altman more cautious than he used to be', 'how often does she make predictions'), names the alternative path (particle_podcast_search_transcripts with person_slug and speaker_statement_characteristics) for finding specific lines, and states the prerequisite of resolving the person first.

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/openWorld/non-destructive, so safety is covered. The description adds genuine context beyond them: that the output is a ranked candidate list rather than a single resolution, that the slug is a stable handle accepted by several named tools, and that bulk queries resolve independently and are grouped. It stops short of noting ambiguity/failure cases (e.g. what happens when nothing matches), which keeps it off 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?

Three sentences, no filler, each doing distinct work: what it returns, the bulk mode, and the disambiguation from siblings. The routing information is last, after the core behavior is front-loaded.

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 three-parameter read-only resolver with no output schema, the description covers result shape (ranked candidates + slug), bulk behavior, and sibling disambiguation. 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 the baseline is 3, but the description contributes meaning the schema does not: that the slug returned is the value to pass into person_slug and guest_slug parameters, and that comma-separated queries are resolved independently and grouped. The limit and output_format semantics are left entirely to the schema.

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

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

States a specific verb and resource ('Resolve a person by free-text name') and immediately names the return shape: ranked candidates with the canonical person slug. It also distinguishes itself from particle_entity_resolve and particle_company_resolve by entity kind, so an agent can pick it 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?

Explicit routing rules: use this for persons, particle_entity_resolve for orgs/places/mixed, particle_company_resolve for companies with known ticker or domain. It also names the bulk pattern (comma-separated query) and the downstream tools that consume 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?

Although annotations already mark this as a safe read-only operation, the description adds substantial behavioral context: default speaker inclusion, ad exclusion, low-sample marking under 20 scored mentions, error behavior for unmatched subjects, and exact agreement with the single-subject share-of-voice tool. This goes well beyond the annotations.

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

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

The description is long but front-loads the core purpose and example, then organizes details about defaults, grouping axes, errors, and alternatives. It is dense but mostly earns its length for a 13-parameter nested tool, though some repetition around grouping axes could be tightened.

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 13-parameter tool with nested objects and no output schema, the description covers the important behavioral surface: scope, defaults, grouping, sample-size warnings, error semantics, and relationships to sibling tools. An agent has enough information to select and 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 schema carries most parameter definitions. The description still adds useful semantics: subjects must be passed in one ordered list, at least one of company/person/entity slug lists is required, and `speaker_statement_characteristics` filters counted lines rather than just annotating them.

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

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

States a specific action — comparing how 2–5 companies, people, or entities are spoken of on podcasts side by side — with a concrete example. It clearly distinguishes the tool from the single-subject `particle_podcast_get_share_of_voice` by emphasizing the multi-subject comparison and aligned outputs.

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 to use this tool and names alternatives for adjacent tasks: single-subject occupation breakdowns, raw mentions, and volume-over-time trends. It also gives clear conditions such as default 30-day window, maximum 365 days, and low-sample behavior.

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 real behavioral detail absent from annotations: pagination by cursor, per-mode scoping, how mention lines are labeled with poles, what happens on unresolved_reference, and that a name-only match is refused. However, roughly a fifth of the text drifts into describing how a sibling tool (search_transcripts) behaves rather than this tool, which dilutes rather than informs this tool's behavior.

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

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

The purpose and mode selection are correctly front-loaded under clear headers, and the three-mode framing is a useful spine. But the definition is long and partly redundant, and the closing "Without a topic" section is largely an essay about particle_podcast_search_transcripts rather than this tool — content that does not earn its place in this definition.

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 23-parameter, nested-object, no-output-schema tool, the description covers everything an agent needs to call it correctly: how to resolve slugs, how the modes differ, how to build the characteristics filter, how guest filters combine, and how to page. Nothing material is left to 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?

Schema coverage is 100%, so the schema already documents each of the 23 parameters, and the baseline would be 3. The description still earns above baseline by explaining cross-parameter interactions the schema only states tersely: which mode makes episode_slug required, which modes honor limit/cursor/context_lines, that sort="strength" is only valid with speaker_statement_characteristics, and the resolve-first workflow for slugs and guest filters.

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 line states a specific verb+resource+scope: "Find dialogue lines where a specific person or company is named in podcast transcripts." It is immediately distinguishable from the siblings that also touch transcripts (search_transcripts for topic discussion, get_mention_trends for frequency), and those distinctions are made explicitly later.

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 guidance is given for all three modes, plus two worked workflow patterns keyed to what the agent already knows (slug in hand vs. wide scan). A dedicated "When NOT to use this tool" section names the two alternatives and the conditions that route to them, so the choice between find_mentions, search_transcripts and get_mention_trends 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 cover the read-only, open-world, non-destructive profile, and the description goes further with real behavioral nuance: ranks are weighted relative to an entity's own baseline so count does not determine rank, and acceleration is not measured on the guests chart. It also reveals that entries carry slugs and quote episode ids usable for chaining. It stops short of describing response shape or pagination, which keeps it below 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-loads the purpose, then usage, then the ranking caveat, then chaining targets — a sensible order. It is dense and somewhat long, and the partial re-listing of chart categories duplicates the `chart` enum description, but every paragraph carries distinct information.

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

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

For a six-parameter tool with no output schema, the description covers what an entry contains (rank, movement, reason, quote, playback link, slug), how to follow up on each object type by name, and the ranking edge cases. Nothing an agent needs to select or 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 coverage is 100%, so the baseline is 3; the description adds value beyond it by grouping the charts (entertainment, sports, books, guests) and explaining what guests ranks, plus the acceleration caveat affecting `sort`. It repeats a fair amount of what the enum descriptions already say, limiting the upside.

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 specific verb and resource: 'What is trending on podcasts... rank the entities... with movement since the previous edition and why it moved.' The entity types it covers are enumerated and it explicitly distinguishes itself from particle_podcast_get_rankings (Apple/Spotify show charts) and particle_podcast_get_mention_trends.

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: call with no arguments for the `all` chart, pick narrower charts by name with groupings listed, `sort=acceleration` for fastest risers. It also states two negative cases with named alternatives, so an agent is routed without reading either schema.

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/openWorld/non-destructive, so the description's real contribution is pay-per-section behavior: lean by default, opt-in sections via `include`, and the warning that full transcripts are large and should be narrowed by speaker/time range. It stops short of any rate-limit, auth, or premium-status note for this tool itself, which keeps it off 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-loads purpose and default behavior, then routes to alternatives — a sensible order. The long inline enumeration of every `include` value largely duplicates the schema enum description, which is the one place it spends words it doesn't need to.

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

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

With no output schema and six parameters, the description covers what comes back, what the lean default contains, how to expand it, and the size caveat on transcripts — enough for an agent to call this correctly and avoid over-fetching. The only omission ('related' in the prose include list) is fully covered by the schema.

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

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

Schema description coverage is 100%, so the schema carries the baseline; the description still adds practical meaning by framing `include` as an opt-in cost/benefit tradeoff and by explaining that transcript_speaker/transcript_start/transcript_end exist to bound a large payload. Minor gap: the prose enumeration of `include` values omits 'related', which only the schema mentions.

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

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

Names a specific verb and resource ('Return a bundled overview of one podcast episode') and immediately enumerates the returned fields (title, podcast, speakers with slugs, top entities, segment/clip counts). It also explicitly differentiates itself from two siblings, so an agent can pick it 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?

Gives an explicit default ('response is lean — counts plus top mentioned entities') and tells the agent exactly which alternative to use for adjacent needs: 'every line about X' → particle_podcast_find_mentions with episode_slug, and ad reads → particle_podcast_get_episode_ads (premium). The when/when-not/alternatives routing is complete.

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

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

Annotations already cover safety (readOnly, non-destructive, openWorld), yet the description adds substantial non-obvious behavior: UTC-aligned zero-filled buckets, Monday-aligned weeks, a 1000-bucket cap, the ~2-year range limit on semantic search, the 'lower bounds for pathologically broad queries' caveat, and the requirement that at least one filter be supplied. It even explains the guest_ filters' episode-level semantics and the unresolved_reference retry flow.

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 when-to-use contrast before dense operational detail; the three paragraphs follow a logical progression (what it computes, when to pick it, how the guest_ filters behave). It is long, but nearly every sentence carries a decision-relevant constraint, so the length is mostly earned rather than 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 22-parameter, zero-required, no-output-schema tool, the description covers the gaps that matter: it explains what the response is (per-bucket counts plus range totals and per-bucket transcript mention counts), the at-least-one-filter precondition, and the keyword/semantic mutual exclusion. 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 coverage is 100%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: guest_field alone charts a field's expert bookings whereas guest_field + company_slug charts company episodes with those experts, and guest_ filters never check who actually spoke. It also clarifies that keyword_search and semantic_search each attach per-bucket mention counts to the response.

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 — time-bucketed episode counts per day/week/month plus range totals — and immediately frames the use case ('how often is X discussed over time'). It explicitly names the siblings it supersedes (particle_podcast_list_episodes, particle_podcast_find_mentions, particle_podcast_search_transcripts) and the related tool it is not (particle_podcast_get_mention_trends).

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 routing rules: use this for trend lines 'instead of paging' the list/search tools, use get_mention_trends when the question is about brand mentions, and get_share_of_voice when the question is who said a keyword. It also states the selection constraint (keyword_search vs semantic_search cannot be combined, semantic requires published_after) and the minimum filter requirement.

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 a safe read-only open-world tool, but the description adds meaningful behavior: default response contents, not_found semantics, recommendation filtering rules, ranking behavior, and suitability-band interpretation. Those details go well 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 front-loaded and purpose-first, with useful routing details. It is somewhat dense and the recommended_podcasts explanation is a long run-on that restates schema details, but it contains little irrelevant 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 complex guest-profile tool with no output schema, the description is essentially complete: it explains default output, optional sections, special return behavior, and the related person tool. Nothing essential is missing 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 schema already documents all three parameters. The description still adds practical meaning for the include sections, especially the pitch-list semantics and filtering of recommended_podcasts, though much of the enum documentation is repeated.

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

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

States a specific resource and scope: a guest's podcast-appearance profile with lifetime stats and frequent podcasts. It explicitly distinguishes this from particle_person_get's biographical profile and notes the not_found case for non-guests.

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?

Tells the agent when to use this tool and when to switch to particle_person_get for people with no podcast appearances. It also explains the purpose of each optional include section, including when to ask for recommendations or in-field appearances.

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 declare readOnly/openWorld/non-destructive; the description adds substantive behavior beyond them: ad-read mentions excluded unless include_ads, the newest day filling in over ~a day with a partial-marked bucket, low-sample flags under 20 scored mentions, the 365-day cap for breakdown/characteristics modes, and the dated semantic change to 'new'. These are exactly the operational caveats annotations cannot convey.

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

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

Front-loaded with purpose and sibling routing before mode detail, and each mode paragraph earns its space. It is unusually long, however, and several label definitions in the compare paragraph repeat what the schema's change/sort descriptions already state, which is the main cost.

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 27-parameter tool with no output schema, the description still conveys return shape (per-podcast rows with counts, deltas, labels, both-window totals; per-bucket series), default behaviors, and prerequisites for each mode. Nothing critical for a correct call 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; the description goes further by explaining cross-parameter interactions (cursor must be reused with the original published_after/published_before, sort defaults shift with change='new'/'returning', lookback_days never shorter than the previous window, breakdown requires published_after). Much of the 'change' label text mirrors the schema, so it is additive but partly redundant.

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 specific verb+resource ('how a person's, company's or entity's podcast mentions are moving') and immediately names the sibling to use instead for discovery ('particle_podcast_get_entity_chart'). The two-mode breakdown further sharpens what the tool returns, so an agent can distinguish it from every listed sibling without opening schemas.

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 examples ('which shows talked about Nike this week versus last?'), mode selection criteria, and named alternatives for adjacent jobs (find_mentions for lines, get_episode_timeseries for role/keyword trends, get_share_of_voice for speaker splits, alert_create for ongoing monitoring). Exclusions are stated, not 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 declare readOnly=true and destructive=false, yet the description still adds substantial behavior: tracking begins May 2026, per-podcast history silently defaults to country=us, category_slug omission means 'overall chart plus every category', slots ignores other filters, and 90 days of one slot fits in a single 100-row page. The per-slot caveat on debuts ('read its episode count and, when shown, its first-episode date before calling it brand-new') is exactly the kind of semantic trap an agent would otherwise fall into.

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 a mode list before any detail, and the bulleted structure maps one bullet per mode, which is easy to scan. It is long and some clauses (the debut episode-count aside, the page-of-100 justification) are dense, but each carries a real disambiguation an agent needs, so little is truly wasted.

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

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

Covers mode selection, defaults, historical boundaries, pagination behavior, and one row-level fact (matched podcast_slug fed into other tools) despite having no output schema and 12 parameters. The return shape is still only partly described — rank fields, whether movers rows show deltas, and exit rows' contents are left implicit — which keeps it short of fully self-contained.

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 mode, change, source, country, category_slug and output_format are already documented and repetition earns no credit. The description does go beyond the schema on cross-parameter interactions — that history needs source+country+category_slug to describe one slot's trajectory, that source narrows but other filters are ignored in slots mode — which is genuine value. Remaining parameters (since/until/cursor/limit) get no extra semantics in the prose.

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

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

Names a specific verb and resource and then splits it into four named modes with distinct returned content, so an agent can tell chart from movers from history from slots without opening the schema. It also distinguishes itself from the sibling particle_podcast_resolve by noting that the at-a-glance case is one call there instead of two here.

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 routing for every mode: slots exists to discover filter values 'not guessed'; history should be pinned to source/country/category_slug because unfiltered history of a popular show runs hundreds of rows; change=debut is prescribed for 'new podcasts/launches' while change=new is warned as mostly returning shows. It also names the alternative tool for the single-podcast case.

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 read-only/safe profile, and the description goes far beyond them: shares can sum past 100% because a person counted under several codes appears in each, groups under 20 are flagged low sample, hosts 'mostly code to media', keyword queries can be refused when a word is too common, and window limits (30 default / 365 entity / 90 keyword) are disclosed. These are the non-obvious behaviors an agent must anticipate before calling.

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 the canonical example question, and each paragraph owns one mode (entity split, keyword split, HOW-they-speak split, chaining/alternatives). It is long and occasionally re-explains what enum descriptions already say (keyword window, examples ordering), which keeps it short of a 5 for an 18-parameter tool.

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 18 parameters, a nested object and no output schema, the description carries the return-shape burden itself: grouped mention lines, share, distinct speakers and episode counts, optional interval buckets, and example quotes with speaker/episode/moment link. Between the body and the complete schema, an agent has everything needed to call correctly and interpret output.

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 carries per-parameter documentation and enum meanings. The description still adds cross-parameter meaning the schema does not: which modes are mutually exclusive (keyword_search vs by/examples/breakdown/speaker_statement_characteristics), how breakdown interacts with by ('must differ'), and the practical consequence of speakers='all'. Some of it (level='major', window defaults) is repetition of schema 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?

Opens with a specific verb and resource: 'Split a person's, company's or entity's podcast mentions by who said them', then names the exact axes (SOC 2018, ANZSRC 2020) and the question it answers. It is immediately distinguishable from find_mentions (raw lines), get_mention_trends (volume over time) and compare_share_of_voice (multi-subject), which are all named.

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 routing: use compare_share_of_voice for two-to-five subjects side by side, find_mentions with the resulting guest_occupation code to read what a group said, search_transcripts for keyword passages, and an explicit 'Not for' clause pointing at find_mentions and get_mention_trends. Preconditions such as the 90-day keyword window and the exclusion of keyword_search from the statement-characteristic modes are stated inline.

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?

Despite annotations already declaring readOnly/openWorld/destructive=false, the description adds substantial behavior context they do not cover: it is free to call, typical latency is 5-10 minutes, and it enumerates the full state machine (queued, admitted, transcribed, failed) with what each implies, including that failure_refund applies on failure.

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 polling instruction, and every sentence carries operational value. The final sentence about the episode_slug edge case is dense and slightly tangled ('for an episode we hold that it never requested, there is no request'), costing some readability.

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

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

With no output schema, the description correctly supplies the return semantics (the four state values and their meanings), which is exactly what is needed for a polling tool. The one gap is that both parameters are optional and the description never states the behavior when neither or both are passed.

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 goes further: it explains that request_id comes from particle_podcast_request_transcription, and that episode_slug resolves your organization's request even after transcription, with an explicit edge case for episodes you never requested. It does not say what happens if both or neither key is supplied.

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

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

States a specific verb (read) plus the resource (the organization's transcription request) and the two lookup keys, so it is unmistakable against the sibling particle_podcast_request_transcription that creates the request.

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 and when-not-to-use guidance: it names itself as the way to wait on a request queued by particle_podcast_request_transcription, prescribes polling 'every minute or so', and explicitly says to poll 'rather than requesting again'. It also names the downstream tools to use once state is transcribed.

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, openWorldHint=true, so safety is covered. The description adds real behavioral context beyond that: results are engagement-ranked, clip_id switches to a detail mode returning description, social-hook intro, speaker and audio URL, and include=['transcript'] attaches dialogue. It doesn't discuss pagination limits or ranking caveats, keeping it short of 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?

Three short paragraphs, front-loaded with what the tool does, then detail mode, then sibling routing. Dense but every sentence carries information; the parenthetical example is illustrative rather than padding. Slightly heavy on nested parentheticals, which is the only thing keeping it from 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?

No output schema exists, so the description bears some burden of return-value explanation, and it delivers for the clip_id detail path while implying list rows carry episode slugs. Pagination via cursor and limit is left entirely to the schema, and the listing row shape is never described, leaving a small gap for a 10-parameter 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 coverage is 100%, so the baseline is 3, but the description genuinely adds meaning: it explains that `speaker` takes a person slug and returns only clips of that person talking ('an insightful Sam Altman clip'), and that clip_id toggles a different response shape rather than filtering a list. Those are interpretive details the schema alone doesn't convey.

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') plus the ranking dimension ('ranked by engagement potential'), and immediately characterizes the content as 'the shareable moments'. An agent can distinguish this from particle_podcast_search_transcripts or particle_podcast_get_episode without opening either schema.

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

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

Explicitly routes between modes and siblings: 'For text-based clip discovery — finding clips about a topic or entity — use particle_podcast_search_transcripts instead' and notes episode slugs 'feed particle_podcast_get_episode'. The single-clip detail path (pass clip_id) is also called out with its own trigger condition.

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/openWorld/no-destruction, and the description goes well beyond them: it discloses that the default lists only ingested episodes, that transcript_status with podcast_slug reaches untranscribed back-catalogue episodes marked requestable, and that transcript, segments, speakers and entities do not exist until a request is made. It also explains output_format trade-offs for chaining.

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 default behavior, then alternatives, then the nuanced filter semantics — a sensible ordering for a 22-parameter tool. Some sentences are dense and could be tightened, but none are filler given the parameter surface area.

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 22-param, no-output-schema tool the description covers the hard parts: default scope, back-catalogue lifecycle, sibling routing, and the guest-filter resolution chain. It names some return fields in passing ('title, duration, speakers, counts') but stops short of describing the overall response shape, which is the only real gap.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds real meaning on top: worked examples of filter combination (guest_occupation="cardiologists" with guest_practicing=true; guest_capacity="executive_founder"), the requirement to resolve words to codes via particle_expertise_resolve first, and the unresolved_reference retry behavior. It does not touch every one of the 22 params, but the ones it covers are the non-obvious ones.

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 episodes across the catalog') plus the filterable dimensions, and explicitly distinguishes itself from two sibling tools (particle_podcast_find_mentions for dialogue, particle_podcast_search_transcripts for ranked topic retrieval). An agent can place it correctly 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?

Gives explicit when-to-use conditions ('episode-level discovery when you only need metadata') and names the two alternatives with the conditions that select them. It also states the default mode versus the transcript_status + podcast_slug path for reaching the back catalogue, and the prerequisite resolve-and-retry flow for the guest_ filters.

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, open-world), and the description adds substantial behavior beyond them: the 2+ appearance floor, the in-window cross-show enforcement, the 5+ minute speaking-time requirement, mononymous-person exclusion, and the 2x spike rule. It also discloses what each row contains and what `include: ["expertise"]` widens.

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 distinction, which is the decision an agent needs first, and every sentence carries filter or routing information. It is on the long side and some sentences (the press-tour shape) are dense enough that a skimming agent could miss the enforcement rules, keeping it shy of 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?

For a 15-parameter, zero-required tool with no output schema, the description covers mode semantics, filter interaction, resolution prerequisites, row contents, and downstream slug reuse. 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 coverage is 100%, so the baseline is 3, but the description adds real semantic value: `podcast_slug` swaps the ranking basis and lifts the lifetime floor, `topic_slug` narrows 'either corpus mode', and expertise filters are gated behind `particle_expertise_resolve` resolution. It does not explain `limit`/`cursor` or `output_format` trade-offs, which are left entirely to the schema.

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

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

States a specific verb+resource ('Browse podcast guests across the catalog') and immediately distinguishes two concrete modes with their ranking rules. It even names the sibling tool to use for the adjacent daily chart use case, so an agent can differentiate 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?

Explicit when-to-use for each mode ('directory' for lifetime-ranked directory, 'trends' for cross-show press tours), plus an explicit alternative: use `particle_podcast_get_entity_chart` with `chart="guests"` for the daily ranked chart. It also gives recovery guidance ('on `unresolved_reference` resolve and retry rather than dropping the filter') and downstream routing via `particle_podcast_get_guest` / `particle_person_get`.

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

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

Annotations already declare read-only, non-destructive, open-world behavior. The description adds substantial context beyond that: related sets are precomputed per show from transcripts, topics, guests, network, and advertisers; they are restricted to the show's language; only shows above a relatedness floor are listed; machine-generated and farmed feeds are never listed; duplicate publisher feeds appear once; and empty-page semantics (first page vs. cursor page) are explained in detail. This is rich behavioral 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?

Despite its length, the description is front-loaded with the core purpose and then structured into distinct, purposeful paragraphs covering results, filtering rules, empty-page behavior, alternatives, and cross-tool chaining. Every sentence adds decision-relevant information for an agent navigating a complex 11-parameter tool with no output 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?

Given 11 parameters, no output schema, and rich annotations, the description is complete for correct invocation: it explains what is returned (slug, score, band, optional basis), how to branch on results, filtering behavior, empty-page semantics, and exact alternatives and downstream tool integrations. Nothing essential for an agent to call this tool 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% for all 11 parameters, so the schema already documents every parameter thoroughly. The description repeats a few parameter hints (e.g., include: ["basis"], preferring band over min_score) but adds no new syntax, format, or constraint details beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific verb (List) and resource (shows most related to a podcast), with a clear scope ('shows like this show'). It explicitly distinguishes from siblings by naming particle_podcast_resolve, particle_podcast_get_guest, and particle_podcast_get_sponsors as alternatives for different needs.

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 scenarios ('use it to explain a recommendation or to keep only pairs related for the reason you care about'), when-not-to-use cases ('Not a topic browser... Not a guest lookup... Not advertiser co-occurrence'), and a direct alternative for a common sub-case ('For the five most related shows inline on a resolve, pass include: ["related"] to particle_podcast_resolve instead of calling this tool'). This is comprehensive routing guidance.

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

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

Annotations already declare readOnly/openWorld/non-destructive, and the description goes well beyond them: it discloses the retrieval mechanism (live nearest-neighbour over episode content, reranked on entities/topics/news story), the per-show cap of two episodes, deduplication of republished content, and exclusion of machine-made or syndication-spam feeds. It also explains the score/band output and the `basis` opt-in.

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 behavior, then usage, then exclusions and slug-routing. Each sentence carries information, though the parenthetical scoring detail and the slug-chaining sentence in the last paragraph make it denser 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 7-parameter, no-output-schema search tool, the description covers what is returned (score + band, optional basis), default behaviors (same_podcast off, dedupe, feed exclusions), and how result slugs chain into get_episode and resolve. Nothing needed 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 coverage is 100%, so the baseline is 3, but the description adds genuine semantics the schema lacks: the '7–30' window heuristic for `published_within_days`, the rationale for `same_podcast` being off by default, and the purpose of `include: ["basis"]`. It does not re-explain `limit`/`cursor`/`output_format`, which the schema already covers well.

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 specific verb and resource — 'Episodes from OTHER shows that cover the same story or subject as a given episode' — and immediately states the ranking basis. It also names the sibling it is not (search_transcripts, find_mentions), so an agent can distinguish it 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?

Gives an explicit trigger ('when you already have an episode and want its coverage elsewhere'), concrete parameter guidance for the news-cycle case, and two named exclusions with the alternative tools to use instead. Both when-to-use and when-not-to-use are 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 only declare readOnlyHint=false and openWorldHint=true, so the description carries the real burden and does so well: exact cost ($0.05/episode, USD, never drawn from included requests), prerequisite (overage billing must be on), refund on failure, non-charged outcomes (existing/queued/already-held requests billed as ordinary lookups), expected latency (5–10 minutes), return states (queued/admitted/transcribed/failed with failure_reason), and post-transcription discoverability across sibling tools. This is unusually complete behavioral disclosure consistent with idempotentHint=true.

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 eligibility rule, then billing, then lifecycle/polling — a sensible order for an agent. The prose is dense and slightly repetitive around billing outcomes, but nearly every clause supplies a fact an agent needs to avoid a wrong or duplicate (paid) call.

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

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

There is no output schema, so the description must explain return values, and it does: the immediate response carries a request state with enumerated values and failure_reason on failure. Combined with cost, prerequisites, latency and handoff to polling/discovery tools, an agent has everything needed to call this correctly and follow up.

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% for the single episode_slug parameter, so the baseline is 3; the description adds value by explaining where a valid slug comes from (list_episodes with transcript_status=requestable and podcast_slug, or get_episode) and that the episode ID serves as the slug for back-catalogue episodes. It stops short of format/syntax examples.

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 ('Request the transcription of a back-catalogue episode') and precisely scopes the eligible set: episodes found in a feed but not yet transcribed, marked requestable by particle_podcast_list_episodes (transcript_status=requestable) or particle_podcast_get_episode. It also clarifies what does not yet exist (transcript, segments, speakers, entities, mentions), so the agent can distinguish it from particle_podcast_get_transcription_request and the search/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?

Explicit when-to-use (only requestable back-catalogue episodes), when-not-to-use ('never call this tool again to poll'), and the named alternative for polling (particle_podcast_get_transcription_request, described as free). It also imposes a procedural precondition rarely stated so plainly: confirm the $0.05 charge with the user first.

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 behavior beyond annotations: forgiving matching, best-match ordering, match_quality, empty-list meaning, premium-plan requirements for certain hydrations, and which fields are always rendered. Annotations already cover read-only safety, so the remaining premium/rate-limit details are not essential, but the description adds rich operational context.

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 purpose and return handle, then organizes advanced filters and hydrations clearly. It is long and somewhat duplicative with the include parameter schema, but most content is relevant and structured rather than 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?

Given 15 optional parameters, no output schema, and complex hydration options, the description is complete enough for correct invocation. It explains return fields, default browsing behavior, result ordering, premium constraints, and when to use follow-up tools.

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 meaningfully supplements the schema with examples and cross-tool guidance for guest filters, topic concentration, popularity, and hydrations, though much of the include list duplicates the very detailed schema description.

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

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

States a specific verb and resource: find a podcast by title, slug, iTunes ID, or RSS URL. It also states what is returned and identifies the resulting slug as the agent-facing handle for other podcast tools, clearly distinguishing it from siblings such as list_episodes and find_mentions.

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 covers multiple usage modes: identifier lookup, forgiving free-text search, no-identifier browsing, filtering by topic/suitability/popularity/guest attributes, and optional hydrations. It also routes agents to alternatives such as particle_podcast_list_episodes when recent_episodes is insufficient and particle_expertise_get for top podcasts by guest field.

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

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

Annotations already declare read-only, open-world, non-destructive behavior, and the description is fully consistent with that. It adds substantial behavioral context beyond annotations: result shape, segment partition semantics, clip overlap behavior, compact-mode tradeoffs, line-characteristic labels, and error behavior when filters remove all 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?

The description is front-loaded and organized with bold headings, and its length is justified by the tool's complexity. However, some points are repeated between the overview and the schema-like parameter notes, and the very long prose could be tighter without losing necessary guidance.

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 30 parameters, no required fields, and no output schema, the description is unusually complete. It explains return formats, segment and clip behavior, compact screening, speaker characteristics, query construction, and filter interactions, so an agent has enough context to invoke the 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%, so the schema already documents the parameters, but the description adds strategic meaning beyond those field descriptions. It clarifies semantic versus keyword search, hybrid intersection behavior, `role` versus `speaker`, guest filter interactions, `speaker_statement_characteristics`, and how constraints compound, which is valuable for a 30-parameter tool.

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: searching the podcast catalog by spoken episode content. It distinguishes semantic, keyword, and hybrid search modes in the first sentence and later names the sibling tool `particle_podcast_find_mentions` for a different retrieval need, so an agent can identify the tool's role without opening the schema.

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

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

It gives extensive when-to-use guidance: semantic vs keyword vs hybrid query construction, when to use `particle_podcast_find_mentions` instead, how to screen many results with `format: "compact"`, and how to handle filters that are stated by the question versus self-added. It also explains alternatives and retry behavior when filters empty results, leaving little to inference.

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

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

Annotations only establish the read-only, non-destructive, closed-world profile. The description goes well beyond: it discloses the ranking order (exact, prefix, substring by story coverage), the query mode's coverage floor ('at least 5 story clusters'), a 200-match page ceiling, and a real caution that the same name sits under several parents so ancestry must be read first.

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 tight paragraphs, front-loaded with the primary browse behavior before the query alternative. It is slightly repetitive with the schema's query-ranking wording, and the downstream-tool sentence could be trimmed, but no sentence is wasted.

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

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

For a 5-param, no-required, read-only browse tool with no output schema, the description covers both modes, ranking, coverage limits, pagination ceiling, and downstream slug usage. It does not describe the shape of an individual returned topic, which is a minor gap given no output schema exists.

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 genuinely non-schema meaning: the parent/child slug convention with an example ('politics/elections') and the fact that parent_slug narrows query to that subtree. Minor redundancy with the schema's own query ranking text keeps it from a 5.

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 ('Navigate the topic taxonomy') and precisely defines both operating modes: no parent_slug returns top-level roots, with parent_slug returns direct children. No sibling tool in this server does taxonomy browsing, so the agent can identify it immediately.

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 contrasts the two paths: walk the tree via parent_slug, or 'to find a topic by name instead of walking the tree, pass query.' It also names the downstream consumers ('topic_slug' filters on particle_podcast_resolve and particle_podcast_list_guests), telling the agent why it would call this before those.

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