particle-pro

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

Beyond the single destructiveHint=false annotation, the description discloses side effects and constraints: the alert backfills the past week without sending emails, filters apply persistently across all channels, speaker_roles is rejected for ENTITY_MENTION, and kind is fixed at creation. This gives an agent an accurate model of what will happen.

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 longer than average but is organized into a clear purpose paragraph, a filters paragraph, and a behavior/forward-reference paragraph. It is front-loaded with the core action and each section earns its place, though a small amount of duplication with the exhaustive schema is present.

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 creation tool with nine parameters, no output schema, and minimal annotations, the description covers the preconditions, filter semantics, error condition, post-creation backfill, and downstream usage. The response shape is implied by the statement that the created alert id feeds the other alert tools, which is sufficient for the agent to invoke correctly.

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

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

Schema coverage is 100% and the schema entries are already very detailed, so the description does not need to compensate. It adds useful workflow framing (e.g., entity slugs come from resolve tools, one alert per entity) but mostly restates what the schema already documents, keeping 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?

The description opens with a specific verb and resource: 'Create an alert that watches a single entity and emails you...' and immediately distinguishes the two kinds (ENTITY_MENTION vs PODCAST_SPEAKER). It also names related tools in the workflow, so the tool's role is unambiguous.

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

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

It gives explicit workflow guidance: resolve an entity first with particle_entity_resolve, then create with the returned slug, and use particle_alert_preview before committing. It also tells the agent to call the tool once per entity and notes that the resulting id feeds subsequent alert tools.

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

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

Even though destructiveHint=true already signals mutation, the description adds important behavioral nuance: the alert stops producing matches, disappears from particle_alert_list, and past matches and deliveries are retained for audit. This goes well beyond the annotation and gives the agent a clear model of the tool's side effects.

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 concise and well-structured: the core action is stated first, followed by the essential soft-delete semantics, and finally the routing guidance to the sibling tool. Every sentence earns its place without redundancy.

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

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

For a one-parameter tool with a clear schema and no output schema requirement, the description fully covers what the tool does, its side effects, and the relevant alternative. Nothing critical is missing for an agent to invoke it correctly.

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

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

The input schema already fully documents alert_id with coverage at 100%. The description does not add parameter-specific guidance, but it also does not need to because the single parameter is straightforwardly described in the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Delete') and resource ('an alert') and immediately clarifies the deletion is a soft delete. It distinguishes itself from particle_alert_update by describing the operational difference, so an agent can clearly tell this tool apart from its siblings.

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

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

The description explicitly names the alternative for pausing an alert (particle_alert_update with is_active=false) and contrasts it with removing an alert. This gives clear guidance on when to use this tool versus the most relevant sibling.

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

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

The readOnlyHint annotation already establishes safety, and the description adds valuable behavioral detail: the `filters` section is omitted when no filters exist, the default response is configuration-only, and include options change the payload. This goes beyond the annotation without contradicting it.

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 efficiently written sentences, each earning its place: the first enumerates the returned config fields, the second handles the conditional omission of filters, and the third covers include options and the sibling alternative. No redundancy or filler.

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

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

For a read-only getter with 4 parameters and no output schema, the description is nearly complete. It covers the primary purpose, optional embedded sections, and the sibling for deeper history. It does not explicitly state error behavior for nonexistent alerts, but that is not critical 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 description coverage is 100%, so the baseline is 3. The description does not add much beyond the schema: it repeats the 'include' behavior and points to particle_alert_list_matches for full pagination, which the schema already states. It adds minor clarity about 'recent matches' but does not compensate significantly.

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: 'Fetch a single alert's full configuration', then enumerates exactly what that includes. It clearly distinguishes this tool from the sibling particle_alert_list_matches by stating that the full paginated match history belongs to that other 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 explicitly tells the agent when to use this tool (for a single alert's config) and when to route elsewhere: 'For the full, paginated match history with transcript excerpts, use particle_alert_list_matches.' It also explains the optional include=['matches'] and include=['deliveries'] behaviors, so an agent knows when to request these additions.

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 the 'List' action is consistent with that. The description adds valuable behavioral context: results are ordered newest first, and each entry carries only the alert id rather than full configuration, implying the list is a summary view and full detail requires particle_alert_get. This goes beyond the structured annotations.

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

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

Two sentences with zero redundancy. The first sentence front-loads the core function and ordering, and the second efficiently explains downstream routing. Every clause contributes to agent decision-making.

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

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

For a simple read-only list tool with fully documented parameters and a readOnlyHint annotation, the description covers the essential behavioral contract: what is returned, in what order, and how the id connects to related tools. There is no output schema, but the description sufficiently hints at the entry shape. Nothing critical is missing for an agent 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 schema already fully documents limit, cursor, and output_format. The description adds little beyond what the schema provides, but the context of ordering and id usage indirectly supports understanding the list's purpose. Baseline 3 is appropriate because the schema carries the parameter documentation burden.

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

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

The description opens with a specific verb and resource: 'List the alerts in your project', and adds the ordering constraint 'newest first'. It distinguishes itself from the sibling alert tools by showing how the returned id feeds into get, list_matches, update, and delete, so an agent can clearly tell listing apart from those operations.

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

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

The description clearly indicates this tool is the entry point for discovering alert ids, then routes the agent onward to particle_alert_get, particle_alert_list_matches, particle_alert_update, and particle_alert_delete. It does not explicitly state when not to use this tool, but the routing creates strong contextual guidance for choosing the correct sibling.

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

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

Beyond the readOnlyHint annotation, the description discloses ordering (newest first), the backfill flag and its implications for email, and the presence of episode/podcast slugs that feed other tools. These are genuinely useful behavioral details not visible in the schema or annotations.

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

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

The description is compact, front-loaded with the core action, and every clause adds information. It avoids restating schema details and packs ordering, backfill behavior, parameter guidance, and downstream tool links into two efficient sentences.

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

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

For a read-only list tool with no output schema, the description covers what the response contains, how to get more detail, how to filter by date, and how returned slugs connect to other tools. Pagination and formatting defaults are already fully specified in the input schema, so nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds value by explaining how view=detailed changes the payload, how after/before scope results, and why the slugs matter. This goes slightly beyond the baseline for fully documented schemas.

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 begins with a precise verb and resource: 'List the matches an alert has caught, newest first'. It clearly distinguishes matches from the alert itself, and the 'payoff of an alert' phrase makes the tool's role obvious relative to sibling 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?

The description gives clear context for when this tool is relevant: after an alert has caught matches, and it explains downstream use of the slugs. It does not explicitly name alternative tools to exclude, but the context is specific enough that an agent would not confuse it with alert listing or podcast transcript search.

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

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

Annotations already carry readOnlyHint=true, and the description reinforces it with 'Read-only — it creates nothing.' It adds useful behavioral context about the historical sweep, the returned count/breakdown/sample, and how read-time projections affect the count, going beyond the annotation without contradicting it.

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

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

The description is front-loaded with the core purpose and workflow, then packs the critical filter semantics and read-only note into a compact paragraph. It is detailed but every sentence carries operational value; no filler or repetition of the schema.

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

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

There is no output schema, so the description compensates by listing the return components (total match count, per-day breakdown, recent sample with episode context). It also covers the window bounds, filter-to-create mapping, and the output_format distinction, making the tool fully callable without external 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?

With 100% schema coverage, the baseline is already strong, and the description adds extra meaning by explaining which filter axes narrow the sweep (languages, speaker_roles) versus which are read-time projections that don't (relevance, source_popularity), and that the count is an upper bound when relevance=RELEVANT. This is exactly the kind of beyond-schema semantic guidance an agent needs.

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 — 'Preview how often an alert would fire BEFORE creating it' — and immediately distinguishes this from creation by showing the workflow (sweep, then call particle_alert_create). This is unambiguous and separates it from sibling 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 explicitly states when to use: to size an alert cadence (REALTIME/DAILY/WEEKLY) or confirm the entity slug, and then directs the agent to call particle_alert_create with the same entity. It also says to pass the intended filters so the estimate matches, which is direct operational 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?

The description discloses important side-effect semantics beyond annotations: only passed fields change, entities/notifications/filters are replaced wholesale, an alert watches exactly one entity, and speaker_roles on an ENTITY_MENTION alert returns unprocessable_entity. These details let the agent predict behavior and avoid errors. The annotations contain only destructiveHint=false, which is not contradicted.

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

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

The description is dense but well-structured, with the core action and update semantics front-loaded in the first sentence and paragraph, and filters covered in a focused second paragraph. It has almost no filler, though a few details are repeated from the schema descriptions, preventing 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 tool with 9 parameters and nested objects, the description is highly complete: it covers replace-vs-merge behavior, constraints, and failure cases, and the schema fully documents every parameter. Since there is no output schema, a brief note on the return value would improve completeness, but correct invocation is well supported.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds cross-parameter meaning that individual schema entries do not fully convey: partial-update vs. replacement, pause/resume semantics, and the invalid filter combination. This moves it above baseline, though the schema already documents most field-level behavior.

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 'Update an existing alert,' a concrete verb and resource. It then distinguishes itself from sibling tools by explaining partial-update semantics, entity replacement, pause/resume via is_active, and the immutability of alert kind, leaving no ambiguity about the operation.

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

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

The description gives explicit alternatives in key cases: use is_active to pause/resume without deleting, and create a new alert to change kind. It also references particle_alert_create.filters for consistency. It does not explicitly contrast against particle_alert_delete or particle_alert_get, but the context is clear enough for an agent to choose this tool.

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

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

The description adds useful behavioral context: identical metering and plan gating apply either way, and the target tool's schema governs arguments. However, the destructiveHint=true annotation signals potential mutating/destructive effects without the description elaborating on what destructive behavior may result from dispatching an arbitrary tool. There is no contradiction, but the description could more explicitly warn about the indirect destructive risk.

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

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

Three dense sentences with no filler. The purpose, the fallback context, the alternative preference, and the discovery path are all front-loaded and each sentence earns its place.

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

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

For a generic dispatcher tool with no output schema, the description explains the mechanism and the fallback rationale well. It lacks explicit guidance about how errors, return values, or destructive side effects are surfaced, and it doesn't mention whether the arguments object is validated before dispatch. The destructiveHint annotation makes the missing cautionary context more noticeable.

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

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

The schema already covers both parameters with 100% description coverage, so the baseline is 3. The description reinforces that arguments must match the target tool's input schema and directs agents to particle_catalog for details, adding modest value beyond the schema fields.

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

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

The description clearly states it dispatches any public Particle tool by name, identifies it as a compatibility fallback, and distinguishes it from direct tool calls. It names particle_catalog as the discovery mechanism, so an agent can tell exactly what this tool does and how it relates to siblings.

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

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

Explicitly says to prefer calling discovered tools directly when the harness allows it, and to use this as a fallback for harnesses that block unadvertised tools. It also tells the agent to use particle_catalog to discover names and schemas, providing clear when-to-use and alternative guidance.

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

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

Annotations provide readOnlyHint=true, and the description adds rich context beyond it: discovery is free while tool execution is metered and plan-gated, responses are graphs where slugs are edges, and tools are lean by default with expand/mode conventions. This materially changes how an agent would call the tool.

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

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

Long, but justified for a catalog tool whose job is to describe the whole API surface. It is front-loaded with the core purpose and the two conventions before the category list, and each section earns its place. A tighter category list would be possible, hence not 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?

Complete for a discovery tool: both modes, the expand convention, the graph/slug traversal model, all categories with default/opt-in status, and the mechanism to advertise opt-in categories are covered. No output schema exists, so the description's explanation of the markdown vs json return shapes fills 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 schema documents both parameters well. The description adds value beyond the schema by explaining the behavioral difference of each mode (menu vs full schemas) and by advising json format only for programmatic chaining. Slight deduction for not detailing the exact categorical menu structure.

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 the full Particle tool catalog') and clearly distinguishes itself from the sibling tool surface by explaining that tools/list only advertises default categories while this tool discovers the rest. The two operating modes (menu without args, schemas with category) are explicit.

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 tells the agent when to call this tool ('call this before invoking a tool you haven't seen advertised') and names the alternatives — advertising opt-in categories via ?include=, ?exclude=, and ?tools= on the connection URL or X-Particle-Include header. 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 only declare readOnlyHint=true, so the description must carry the rest — and it does add real behavioral context: the default response is lean, a section is flagged as premium (`podcast_recommendations`), and `people` slugs feed `particle_person_get`. It stops short of covering pagination, rate limits, or error behavior, so not a 5.

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

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

Three sentences, front-loaded with the core purpose before the optional sections and the alternative-tool note. The include enumeration largely duplicates the schema, which is mild redundancy, but nothing is wasted or buried.

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

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

There is no output schema, so the description carries the burden of describing the return payload — and it does, itemizing the identifiers, name, and description, plus what each optional section yields. Combined with the routing guidance, 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 already 100%, setting a baseline of 3, but the description adds value the schema does not: it explains the cross-tool linkage (person slugs feed `particle_person_get`) and reinforces the lean-by-default include semantics. `product_status` filtering is left to the schema, which fully documents 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?

States a specific verb and resource ('Return a bundled profile for one company') and enumerates exactly what the bundle contains (identifiers, name, description). It also routes away from a near-neighbor by naming `particle_company_get_podcast_ad_presence` for sponsor analytics, so the agent can distinguish it without opening a schema.

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

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

Gives explicit when-to-use guidance for each optional section via `include`, states the default is lean and to request only what is needed, notes you can skip `particle_company_resolve` when the domain is known, and names an alternative tool for a different use case. When/when-not/alternative are all covered.

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

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

The readOnlyHint=true annotation already establishes that this is a safe read operation. The description adds valuable behavioral context beyond the annotation: it returns candidate matches, requires at least one identifier, ANDs multiple identifiers together, and explains the agent-facing identifier fallback chain (slug -> domain -> id). No contradiction with annotations.

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

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

The description is two compact paragraphs with no filler. The first sentence front-loads the core purpose and identifier scope; the rest covers downstream usage, constraints, and sibling differentiation. Every sentence earns its place.

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

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

For a resolve-style tool with no output schema, the description covers what the agent needs: accepted identifier types, required input semantics, output identifier fallback, downstream tools to use with the result, and the relevant alternative for non-company entities. The annotations cover safety, so no further behavioral disclosure is essential.

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 each parameter is already documented in the schema. The description adds meaningful cross-parameter semantics that the schema does not: at least one identifier is required, multiple identifiers are ANDed for disambiguation, and the output identifier should be forwarded to downstream tools. This exceeds the baseline for schema-covered parameters.

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

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

The description states a specific verb and resource: 'Resolve a company' and enumerates the identifier types supported. It also distinguishes itself from particle_entity_resolve by specifying that people and other knowledge-graph entities are out of scope. This makes it easy for an agent to know exactly what the tool does and what it does not do.

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

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

The description gives explicit when-to-use guidance: resolve companies by name/ticker/CIK/QID/domain, and pass the returned identifier to specific downstream tools. It also gives a clear when-not-to-use alternative: 'For people or other knowledge-graph entities (not companies) use particle_entity_resolve instead.' This is strong 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?

The readOnlyHint annotation already establishes the operation is safe, and the description adds useful behavioral context: what fields the response contains, the conditional presence of person_slug/company_slug, and that linked entities should be handled through other tools. This goes beyond the annotation without contradicting it.

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

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

The description is compact and well-structured: first the core function, then the primary use case, then explicit routing to siblings and downstream consumers. Every sentence adds information without redundancy or filler.

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

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

For a simple read-only entity lookup with two well-documented parameters and no output schema, the description covers the return content, the intended use case, the alternatives, and downstream integration. An agent has enough context to select and invoke this tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The tool description itself adds little parameter-specific meaning beyond the schema, though the entity_slug schema description supplies examples and sources, and the output_format schema description explains the markdown/json tradeoff.

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

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

The description states a specific verb and resource: retrieving a single knowledge-graph entity's profile with name, kind, description, and Wikipedia link. It also distinguishes itself from the person/company getter siblings by explicitly noting those return fuller profiles for linked entities.

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

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

The description gives explicit when-to-use guidance: confirm what a slug from particle_entity_resolve refers to, especially for non-person/non-company entities. It also names the preferred alternatives for person and company entities, and even lists downstream tools that consume entity slugs.

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

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

Annotations already declare readOnlyHint=true, and the description goes well beyond that by disclosing the return behavior: each candidate carries a type and canonical slug, slugs route into specific downstream tool parameters, and bulk queries are resolved independently with limit applying per query. No contradiction exists with 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 front-loaded with a clear purpose, uses compact bullets for slug routing, and includes only decision-relevant guidance. Every section earns its place, with no fluff or repetition.

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

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

Despite having no output schema, the description defines the essential contract: candidates expose type and canonical slug, and it maps each slug to the exact parameters and sibling tools that consume it. Combined with usage guidance and bulk behavior, the agent has everything needed to select and 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?

The input schema already provides 100% coverage of both parameters, including examples, case-insensitivity, default limit, and grouping behavior. The description's bulk and per-query-limit statements largely restate this, adding emphasis but little new semantic 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?

The description immediately states a specific action and resource: resolving any named thing by free-text name in one union search. It clearly distinguishes itself from sibling resolve tools by covering person, company, place, and other entities, and by explaining that candidates carry a type and canonical slug.

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

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

The description explicitly tells the agent to use this tool first when only a name is known and the entity kind is unknown. It also names the alternatives for known-person and known-company cases, and gives concrete bulk-resolution usage guidance, making the selection criteria 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 only declare readOnlyHint: true, so the description carries the burden of behavioral detail. It adds valuable context: the default response is lean, optional sections require explicit requests, podcast appearances include follow-up slugs, and `output_format` choices affect LLM readability versus programmatic use.

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

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

The description is compact, front-loaded with the core purpose, and every sentence serves a function: scope, optional sections, default behavior, and sibling-tool routing. No wasted words.

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 lookup with complete schema documentation, no output schema, and no nested objects, the description supplies all necessary calling context: what the profile contains, how to get optional sections, what follow-up data is included, and when to use a different 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 description need not re-document parameters. It adds some contextual reinforcement around `include` sections, but mostly repeats the schema descriptions rather than providing new parameter-level meaning.

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

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

The description states a specific verb and resource: 'Return a person's profile: name, current role, and bio, keyed by the canonical person slug.' It clearly distinguishes from related tools by naming `particle_person_resolve` as the slug source and `particle_podcast_get_guest` as the analytics-focused alternative.

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

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

The description gives explicit routing guidance: use `particle_podcast_get_guest` for podcast-guest analytics with the same slug, and implies `particle_person_resolve` as a prerequisite for obtaining the canonical slug. It also explains when to request optional `include` sections.

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

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

The readOnlyHint annotation already signals no mutation; the description adds valuable behavioral context: it returns ranked candidates, produces a canonical stable slug, and explains that bulk queries resolve independently in one call. This gives an agent a clear mental model of the tool's behavior without contradicting the annotation.

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 tightly structured and front-loaded: purpose first, then output semantics, then bulk mode, then tool-selection alternatives. Every sentence serves a distinct purpose with no repetition or filler.

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

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

For a read-only resolve tool with no output schema, the description covers the essential decision points: what it returns, how the slug is used downstream, how to do bulk lookups, and which alternatives to choose. The only minor gap is a precise description of the ranked-candidate response structure, but the schema and slug explanation compensate adequately.

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 query, limit, and output_format well. The description reinforces the comma-separated bulk behavior and the purpose of the slug, but adds little semantic value beyond what the parameter descriptions already provide.

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

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

The description opens with a specific verb and resource: 'Resolve a person by free-text name.' It clearly distinguishes this tool from the related entity and company resolvers, and explains what the output is (ranked candidates with a canonical person slug).

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

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

Usage guidance is explicit and actionable. It names particle_entity_resolve for organizations, places, and mixed/unknown kinds, and particle_company_resolve for companies with a known ticker/domain. It also documents the bulk-resolution use case via comma-separated queries.

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 readOnlyHint annotation, the description discloses concrete behavior: summary returns episode metadata plus the first 10 mention-only lines, detail returns full mention windows with context_lines, limit/cursor apply only to summary, and up to 10 comma-separated episode slugs can be passed. It also explains pagination, output_format trade-offs, and case-insensitive slugs—none of which are visible from the annotation alone.

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

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

The description is long, but every block earns its place: purpose, mode semantics, workflow, examples, exclusion rule, and required inputs are clearly separated with headers. The core purpose and the most important distinction (summary vs detail) are front-loaded before the examples.

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 14-parameter tool with no output schema and only a readOnly annotation, the description is remarkably complete. It defines response shapes for both modes, explains when each mode is appropriate, states required inputs and slug-resolution prerequisites, covers pagination and multi-episode drill-in, and documents the sibling to use instead. Nothing essential for correct invocation or interpretation 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%, but the description adds substantial meaning on top: the format parameter selects two very different response shapes, episode_slug supports comma-separated multi-get in detail mode, limit/cursor are summary-only, context_lines is detail-only, and one of person_slug/company_slug/entity_slug must be resolved first. This goes well beyond the baseline expected when the schema already documents each field.

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

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

The opening sentence names the verb and resource precisely: 'Find dialogue lines where a specific person or company is named in podcast transcripts.' The two response modes and the explicit 'When NOT to use' section differentiate it from the paraphrase-tolerant search sibling, so an agent can distinguish it from particle_podcast_search_transcripts without inspecting 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?

The description gives a full workflow: use summary first when no episode is known, then drill in with detail; skip summary when an episode slug is already available from tools like particle_podcast_get_episode. It also names the alternative for topic-level conversations ('use particle_podcast_search_transcripts instead'), making the selection rule 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?

Beyond the readOnlyHint annotation, it discloses that the default response is intentionally lean, that full transcripts are large and should be narrowed with transcript_speaker/transcript_start/transcript_end, and that 'entities' returns the complete list instead of the top 20. No trait contradicts 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 purpose is front-loaded in the first sentence, and each subsequent sentence provides actionable routing or behavioral detail. The description is long, but the length is earned by the number of optional sections and alternatives it must disambiguate.

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 supplies a solid mental model of the return payload and optional response sections. It also covers the two important edge behaviors — transcript size and the difference between the included related episodes and the full ranked list — so an agent can call it correctly without more context.

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?

Although the schema already covers all 6 parameters, the description adds operational meaning: it explains what each include value yields, notes defaults, flags transcript size, and clarifies that episode_slug can be a slug or canonical ID. This goes well beyond the structured definitions.

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 first sentence names the exact operation ('Return a bundled overview of one podcast episode') and enumerates the payload: title, podcast, speakers with entity slugs, top mentioned entities, and segment/clip counts. It distinguishes itself from sibling tools by later stating that mention-level queries belong to particle_podcast_find_mentions and ad-read queries to particle_podcast_get_episode_ads.

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 guidance for optional include sections and names direct alternatives with conditions: use particle_podcast_find_mentions for 'every line about X in this episode' and particle_podcast_get_episode_ads for ad reads. It also tells the agent to call particle_podcast_list_related_episodes when the full ranked related list with match basis is needed rather than the five included via 'related'.

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 only readOnlyHint provided, the description carries the full behavioral burden and delivers: UTC-aligned, zero-filled, Monday-aligned week buckets, a 1000-bucket cap, range totals, exact vs semantic per-bucket counts, and the same similarity threshold as search_transcripts. This goes well beyond what annotations or schema alone convey.

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

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

The description is dense but well structured: opening purpose, filter parity, search-mode caveats, usage guidance, bucketing behavior, and required-filter constraint. Every sentence earns its place, and the most important identification cues are 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 15-parameter tool with no output schema, the description covers filters, time semantics, caps, and invocation constraints thoroughly. It falls just short of fully specifying the returned payload structure beyond 'counts', 'range totals', and per-bucket mention counts, though the high-level return contract is clear enough for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by noting that filters are shared with list_episodes, that at least one of six filters is required, and that keyword/semantic searches add per-bucket mention counts. This is meaningful additional context, though not exhaustive per-parameter color.

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, purpose-built definition: time-bucketed episode counts for answering 'how often is X discussed over time'. It clearly distinguishes this aggregation tool from the list/search siblings by focusing on trend lines over paging.

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

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

It explicitly says to use this tool for trend lines instead of paging particle_podcast_list_episodes, particle_podcast_find_mentions, or particle_podcast_search_transcripts. It also states the required filter condition and the exclusive search-mode constraints, leaving no ambiguity about when to invoke it.

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

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

Annotations only declare readOnlyHint: true, and the description adds meaningful behavior beyond that: the not_found case for non-guests, the default response profile plus optional include sections, and the recommended_podcasts pitch-list behavior. It does not contradict the annotation and gives the agent enough to anticipate the response shape.

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

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

The description is front-loaded with the core purpose, then organized by optional sections and finally the error-routing note. Every sentence adds distinct information; the length is justified by the number of include options and the not_found behavior.

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

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

For a read-only getter with three parameters and no output schema, the description covers all essential context: default response, optional sections, slug source, behavior for no appearances, and the sibling fallback. No critical operational detail seems 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 enriches parameter meaning: it explains that episode/podcast slugs in 'appearances' enable follow-up calls, and it clarifies the recommended_podcasts pitch-list structure with 'branch on each row's band'. It also gives slug provenance via list_guests/person_resolve/entity_resolve.

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

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

The description uses a specific verb-resource pairing: it fetches a guest's podcast-appearance profile and enumerates the contained stats (lifetime appearances, distinct podcasts, first/last appearance, frequent podcasts). It explicitly distinguishes itself from particle_person_get by noting that the same slug returns the biographical profile, so an agent can tell them apart.

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 selection guidance: use particle_person_get for biographical profiles and for people who exist but have never appeared on a podcast (not_found), implying particle_podcast_get_guest is for podcast-appearance data. It also names follow-up call possibilities from the include sections, which helps an agent decide when to request 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?

The readOnlyHint annotation is consistent with the description, and the description adds substantial behavior beyond the annotation: slots mode ignores other filters, cursor is unsupported in movers mode, since/until apply only to history, and returned rows carry podcast_slug for chaining into other tools. It also discloses the markdown-vs-json output_format tradeoff.

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 well-structured with bulleted modes and a clear closing paragraph, which is appropriate for a complex 12-parameter tool. It loses a point because the mode bullets partially restate the mode parameter's schema description, but there is no fluff or irrelevant detail.

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

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

For a tool with no output schema, the description covers mode interactions, parameter constraints, filter discovery, podcast_slug chaining, and output-format behavior—strong coverage for a read-only tool. The main gap is that the full return row shape beyond podcast_slug is left implicit, which an output schema or a clarifying sentence would close.

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 all 12 parameters are already individually documented. The description adds valuable cross-parameter semantics, such as how podcast_slug alters chart/history behavior, which parameters are mode-specific, and how source narrows country/category listings in slots mode.

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 clear resource ('Podcast chart rankings from Apple Podcasts and Spotify') and immediately enumerates the four modes, making the tool's function unmistakable. It also differentiates itself from sibling podcast tools by explicitly routing single-podcast chart lookups to particle_podcast_resolve.

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

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

It gives concrete when-to-use and when-not-to-use guidance: for at-a-glance chart presence, use particle_podcast_resolve with include:['rankings'] instead of this tool. It also instructs the agent to use slots mode first to discover valid filter values rather than guessing them.

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 provide readOnlyHint=true; the description adds meaningful behavioral context beyond that, including the engagement-ranked listing behavior, the clip_id detail mode, transcript inclusion semantics, and the practical warning that JSON output is noisier for LLM reading. No annotation contradiction.

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 paragraphs front-load the core purpose, then cover the detail mode and the sibling alternative. Every sentence earns its place; no filler or redundant restating of the schema.

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

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

For a tool with 10 optional parameters and no output schema, the description covers the main usage modes, filtering dimensions, pagination cursor, and routing to related tools. It could be slightly richer about what the listing rows contain beyond episode slugs, but the schema and provided detail-mode field list make it sufficiently complete.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely useful semantics: speaker expects a person slug and returns only clips of that person talking, clip_id switches to detail mode, include only applies with clip_id, and output_format has LLM-facing vs programmatic tradeoffs. This goes beyond the schema's brief field descriptions.

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

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

The description names a specific verb and resource — 'Browse AI-extracted highlight clips' — and clearly distinguishes this from text-based discovery via particle_podcast_search_transcripts. It also clarifies the detail-mode variant via clip_id, so an agent can immediately tell what the tool is for.

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

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

The description explicitly tells the agent when to use this tool vs alternatives: use particle_podcast_search_transcripts for topic/entity discovery, and use clip_id here for full clip detail. It also routes episode slugs to particle_podcast_get_episode, giving clear selection 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?

The readOnlyHint annotation already establishes the safety profile, so the description does not need to restate that. The description adds useful context about scope ('across the catalog') and the kind of metadata returned ('title, duration, speakers, counts'), but it does not disclose pagination behavior, output shape, or any rate-limit considerations. This is adequate but not rich beyond the annotation.

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

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

The description is compact and front-loaded: the first sentence states the core function and filter categories, and the second sentence gives actionable routing to alternatives. No word is wasted, and every sentence contributes either to understanding or usage. It is appropriately sized given the tool's 14 parameters.

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

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

For a read-only list tool with no required parameters and a fully described schema, the description provides the missing high-level framing: what kind of discovery this is for, what data is returned, and which siblings to use instead. The absence of an output schema is mitigated by the explicit mention of metadata fields. An agent has enough context to select and 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 input schema already documents all 14 parameters thoroughly with examples, defaults, and constraints. The description merely summarizes filter categories ('podcast, person, company, language, date range, duration, or transcript availability') that are already present in the schema, adding no new semantic meaning. Baseline 3 is appropriate.

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

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

The description opens with a specific verb and resource: 'List episodes across the catalog with rich filters.' It also distinguishes itself from nearby siblings by naming particle_podcast_find_mentions and particle_podcast_search_transcripts as alternatives for different needs. An agent can immediately understand what this tool does and how it differs from similar tools.

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

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

The description gives explicit usage context: 'Use this for episode-level discovery when you only need metadata.' It also provides clear when-not-to-use guidance by pointing to particle_podcast_find_mentions for dialogue around a person and particle_podcast_search_transcripts for ranked retrieval by topic. This is direct routing to alternatives, not just vague context.

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=true, but the description discloses far richer behavior: the 2+ appearance floor in directory mode, the exact press-tour shape in trends mode (distinct podcasts, 5+ minutes speaking time, mononymous exclusions, 2x spike over baseline), and the one-off guest inclusion when podcast_slug is used. This goes well beyond the structured annotations.

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

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

The description is longer than average but information-dense, front-loaded with the core purpose and then structured as two clear mode bullets. Subsequent sentences explain parameter interactions and downstream tool usage. Every sentence adds value, though the trends bullet is slightly verbose and could be trimmed without losing essential criteria.

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, multi-mode tool with two enums, four optional filters, and no output schema, the description covers all essential behavior: default mode, mode-specific thresholds, parameter combinations (podcast_slug switching to a show roster, topic_slug narrowing), and the read-only nature. The only omitted specifics, like podcast_slug being ignored in trends mode, are already present in the schema parameter descriptions.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaningful context for mode, podcast_slug, and topic_slug, including how they interact and what changes in each mode. It also explains the intent behind output_format's markdown vs json distinction. It does not repeat trivial details for limit/cursor, which is acceptable given full schema coverage.

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

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

The description opens with 'Browse podcast guests across the catalog' — a specific verb and resource — and immediately distinguishes two modes, directory and trends. It clearly differentiates this from sibling tools like particle_podcast_get_guest (which focuses on a single guest) and podcast list tools for episodes/clips by centering on guests across the catalog or one show.

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

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

The description gives explicit guidance on when to use each mode: directory for lifetime rankings, trends for cross-show press tours with defined criteria. It also advises feeding guest slugs into particle_podcast_get_guest or particle_person_get, showing downstream routing. It does not explicitly contrast with all sibling list tools, but the mode selection and parameter constraints are clear enough.

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

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

Beyond the readOnlyHint annotation, the description discloses key behaviors: results are precomputed, restricted to a single source podcast, ranked best-first, filtered by relatedness score, language, popularity, suitability, and publisher exclusion. It also discloses edge behavior ('An empty page is not an error') and explains the meaning of score bands and the 'basis' object. The description carries the behavioral transparency burden almost entirely on its own.

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 earned: it front-loads the core purpose in the first sentence, then organizes additional context into a few dense, high-value paragraphs. Every sentence adds operational meaning (empty-page semantics, band meanings, output format guidance, filter behavior) rather than restating schema fields.

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

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

Given the tool's complexity (filters, output formats, result semantics, sibling relationships), the description covers the operational surface thoroughly: what results look like, how scores/bands behave, what filters do, when to use JSON vs markdown, and how this tool differs from alternatives. There is no output schema, so this prose carries the full burden and succeeds.

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

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

The input schema already covers every parameter with detailed descriptions, so the description needn't duplicate that. It adds useful semantic context beyond the schema: how scores/bands should be interpreted, how include affects output, when JSON output is appropriate, and how objects can be fed from resolve calls. Minor gap: some params like limit/cursor aren't explicitly called out in prose, but the schema covers them 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?

The description opens with a specific verb and resource: 'List the shows most related to a podcast, best first.' It clearly identifies the tool as a show-level related-list (not episodes or guests), and explicitly contrasts it with sibling tools like particle_podcast_resolve, particle_podcast_get_guest, and particle_podcast_list_related_episodes. An agent can distinguish it from alternatives 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?

The description gives explicit when-to-use and when-not-to-use guidance: it says to use particle_podcast_resolve for topic lookups, get_guest for people, and list_related_episodes for episode-level recommendations. It also explains when to prefer include='basis' or output_format='json'. This is exemplary usage clarity.

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 give readOnlyHint=true, but the description adds substantial behavioral context beyond that: it explains the ranking signals (salient entities, topics, news story), that each show contributes at most two episodes, republished content is collapsed, and machine-made/syndication feeds are excluded. It also clarifies how same_podcast changes behavior. This is far beyond the annotation and helps the agent set expectations.

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 extremely well-structured: it front-loads the core purpose and ranking logic, then gives usage guidance, exclusions, and parameter hints in a logical flow. Each sentence earns its place; there is no filler or redundancy.

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

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

Despite having no output schema, the description tells the agent what to expect (calibrated score and a band) and how to obtain more detail (include:['basis']). It also cross-references related tools for downstream steps (episode slugs feed get_episode, podcast slugs feed resolve), giving a complete picture of how to use the result. For a tool with 7 parameters, this is comprehensive.

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 valuable semantics: published_within_days is tied to news-cycle usage, include:['basis'] reveals signals, same_podcast explains exclusion logic, and output_format guidance clarifies when each serialization. These enrich the raw schema descriptions considerably.

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 precisely what the tool does: returns episodes from other shows covering the same story/subject as a given episode, using a nearest-neighbour search with reranking. It explicitly distinguishes itself from sibling tools (search_transcripts, find_mentions) by naming what it is NOT for, so an agent can immediately select it correctly.

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

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

Provides explicit when-to-use ('who else covered this?') and when-not-to-use directives, naming the exact alternatives (particle_podcast_search_transcripts for dialogue, particle_podcast_find_mentions for entity mentions). Also gives parameter-level guidance (published_within_days 7–30, same_podcast semantics) that helps the agent choose the right invocation.

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 readOnlyHint annotation, the description reveals important behavior: forgiving free-text matching, best-match-first ordering, the match_quality marker, empty-list semantics, the recently-updated fallback when no identifiers are provided, and premium-endpoint requirements for certain hydrations. It also clarifies that high-level bias and suitability enums are always returned without opt-in. No contradiction with 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 front-loaded with the core purpose and return fields, then organized into scannable bullets for hydrations. It is fairly long, but the complexity of 10 optional parameters and 7 include options justifies the length. Some redundancy with the schema's include descriptions keeps it from being maximally concise.

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 that there is no output schema, the description carries the burden of explaining return behavior and does so thoroughly: lookup modes, returned fields, matching tolerance, empty-list meaning, browsing mode, filters, hydration options, premium-plan caveats, and downstream tool usage. Minor gaps like error behavior for invalid exact identifiers do not undermine selection and 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?

The input schema already describes all 10 parameters in detail (100% coverage), so the baseline is 3. The description adds some extra parameter-selection guidance, such as the all-identifiers-omitted browsing mode, the agent-facing slug handle, and grouping topic_slug/suitability_tier/min_popularity as narrowing filters. However, much of the hydration detail repeats the schema, so it does not reach 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?

The description opens with a specific lookup verb and resource: 'Find a podcast by free-text title, exact slug, iTunes ID, or RSS feed URL.' It also states the returned payload (slug, title, episode count, bias, recurring speakers) and positions the slug as the handle for downstream podcast tools, making its role distinct from the other resolve-type siblings.

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

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

The description explains when to use the tool for identifier-based lookup, when to browse by omitting identifiers, and how to narrow browsing via topic_slug, suitability_tier, or min_popularity. It explicitly routes follow-up work to sibling tools, e.g. using particle_podcast_get_rankings for movers/history, particle_podcast_list_episodes for more episodes, and particle_podcast_find_mentions/list_episodes/get_sponsors once a slug is resolved.

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=true, so the description carries the full burden of behavioral disclosure. It delivers substantial detail: segment contiguity and partition semantics, match-window context defaults, how `keyword_match: "ranked"` relaxes the keyword side, how `role` distinguishes speaking vs mentioned entities, the difference between `output_format` modes, and even error behavior ('the error names the specific parameter responsible'). No contradiction with annotations.

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

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

The description is long but well-structured: it front-loads the core purpose, uses bolded section headers ('Choosing your query', 'Start broad', 'Note on role'), and organizes parameter guidance coherently. There is minor redundancy with the schema (e.g., `context` and `output_format` described in both places), but no wasted filler; the length is justified by the tool's complexity.

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

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

For a tool with 19 parameters and no output schema, the description is unusually complete. It covers the shape of results (segments + clips), how segments map to transcript lines, how to get full segment line ranges via `particle_podcast_get_episode`, the closed interplay between search modes, filter compounding risks, pagination behavior is left to schema but search strategy is fully explained. An agent has enough context to call this tool correctly in most scenarios.

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

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

Schema coverage is 100%, so baseline is 3, but the description significantly enriches parameter meaning. It explains that `semantic_search` carries the idea while `keyword_search` requires literally spoken words, warns against putting names in `semantic_search`, clarifies quoted phrases, and explains `keyword_match`, `role`, `context`, and `output_format` in ways the schema does not. This materially improves correct parameter usage.

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: 'Search the podcast catalog by what is said in episodes,' and clearly defines the three search modes and the unit of output ('one segment of one episode with bounded transcript windows... plus any highlight clips'). It also names the sibling alternative `particle_podcast_find_mentions`, so an agent can distinguish this tool from related ones without reading 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?

Usage guidance is explicit and actionable: 'Use this for "find dialogue *about* a topic". For "every line *naming* a person or company" use `particle_podcast_find_mentions` instead.' It also routes segment/clip retrieval to `particle_podcast_get_episode`, states 'There is no separate clip-search tool,' and gives a clear query workflow ('Start broad, then narrow'). This goes well beyond implied usage.

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

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

With readOnlyHint=true covering the safety profile, the description adds meaningful behavioral context: it lists top-level examples, states 'direct children,' and explains the parent/child slug convention. It doesn't address pagination or malformed parent_slug, but those are not critical for a read-only browse operation.

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 front-load the purpose and then give the two modes and the slug convention with no filler. The final purpose clause is a minor echo of 'navigate,' but it is short and does not hurt clarity.

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, zero-required-parameter browse tool, the description covers the core behavior and invocation modes; the schema handles limit, cursor and output_format. No output schema exists, but the output_format parameter description already explains the markdown/JSON distinction, so the agent has what it needs to call correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the slug convention ('parent/child' and the example politics/elections) and how parent_slug selects a level, going slightly beyond the schema.

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

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

States a specific verb and resource ('Navigate the topic taxonomy') and precisely defines behavior for both invocation modes: top-level roots without parent_slug, direct children with parent_slug. This clearly distinguishes it from the unrelated alert/podcast/person siblings around it.

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

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

The description gives clear, explicit context for when to call: to browse or locate well-named topic categories, with parameter-dependent modes. It names no alternative or exclusion, but no sibling tool offers the same hierarchy-browse role, so a 4 is appropriate.

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