IndustryLens

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

Goes beyond the readOnlyHint/openWorldHint annotations by disclosing the negative-result behavior: a { covered: false } payload for companies not publicly tracked. That is a meaningful edge case an agent cannot infer from annotations or schema; it does not cover result fields or ordering, which are minor given the closed-world, read-only profile.

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

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

Three tight sentences with the trigger front-loaded and no filler; every sentence carries distinct information (trigger, input, return shape).

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

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

With no output schema, the description usefully sketches the response (a set of tracked companies in the same market, plus the covered:false case), which is enough to call and interpret it. It does not say what attributes each returned competitor carries or whether results are ranked, leaving a small gap for a discovery 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% and already documents name, domain (marked Preferred), and limit with default/max. The description only echoes that a domain or name can be supplied, adding no new syntax, precedence, or fallback detail 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 ('find who competes with a company') and describes the return ('other companies IndustryLens tracks in the same market'), which separates it from profile- or landscape-oriented siblings like get_competitive_profile and get_market_landscape.

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

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

Gives an explicit trigger ('Use when the user asks who else competes in a company's market, or wants a peer/competitor set'), so the agent knows the activation condition. It stops short of naming when to prefer a sibling such as get_competitive_profile or get_market_landscape instead.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, so safety and scope are covered. The description adds value beyond them by disclosing the return payload: content_json with pricing, recent moves, positioning, displacement signals, and when-to-choose, plus metadata. Minor gap: no mention of behavior for an unknown or unpublished slug.

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

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

Three tight sentences, front-loaded with the usage trigger, then the operation, then the return shape. No redundant restatement of the tool name 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?

With one required parameter, no output schema, and annotations covering the safety profile, the description is nearly sufficient — it even enumerates the return contents. The only missing piece is what happens on a missing/invalid slug, which matters for a slug-keyed fetch.

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 already documents the single slug parameter, including its origin (list_comparisons). The description repeats that origin but adds no new syntax, format, or constraint detail, so the baseline 3 applies.

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

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

States a specific verb and resource: fetches the full structured body of one published competitor comparison by slug. It is clearly distinguishable from list_comparisons (which enumerates slugs) and from the other get_* siblings, which cover different resources.

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?

"Use when the user wants the full head-to-head detail for one published comparison" gives an explicit trigger, and the parenthetical routes the agent through list_comparisons first to obtain the slug. It doesn't explicitly state the inverse case (use list_comparisons for summaries/listing), but the sequencing implication is strong.

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

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

The description adds rich behavioral details beyond annotations: it explains that firmographics fields may show 'collected: false' with a note until enrichment is ready, describes the strategic move format (existence of shift + was→now summary + analysis date), and defines fallback behavior ({ covered: false }). It also clarifies batch result ordering and status tags, providing strong transparency for a read-only tool.

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

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

The description is front-loaded with a clear 'Use when...' clause and packs significant information into one paragraph efficiently. However, it is dense and could be more scannable with structured formatting; every sentence does contribute, so it avoids waste.

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

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

With no output schema, the description does a thorough job of explaining return values: firmographics details, strategic move structure, report links, the { covered: false } case, and batch result format. It covers all essential aspects for an agent to invoke and interpret 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 coverage is 100%, so the baseline is 3. The description adds value by explaining the batch behavior of 'companies' (up to 10, order preserved, status tags per result) and by emphasizing that domain/name are alternatives, which enriches semantics beyond the schema's individual parameter descriptions.

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

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

The description clearly states the tool's purpose with a specific verb (get) and resource (competitive profile), and lists the returned data (firmographics, strategic moves, reports). However, it does not explicitly differentiate itself from siblings like find_competitors or get_market_landscape, despite overlapping use cases such as 'who competes with a company'.

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 provides clear trigger conditions ('Use when the user asks who competes...'), but lacks explicit exclusions or guidance on when to choose alternatives. The batch usage note ('Pass companies instead of domain/name...') adds helpful context but does not fully cover decision criteria.

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

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

Annotations already declare readOnly and closed-world, yet the description still adds real behavior: newest-first ordering, dates are guaranteed real analysis dates, the { covered: false } fallback with a CTA for untracked companies, and per-entry result blocks returned in input order for batch calls. These are operational traits an agent cannot infer from 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?

Front-loaded with the trigger condition, then scope, then return shape, then the batch variant — a sensible order. It is dense but the batch paragraph partly duplicates the schema, costing a bit of economy.

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

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

With no output schema, the description carries the return contract itself: feed ordering, date provenance, the covered:false case, and the batch result structure. An agent has enough to call this correctly and interpret the response.

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 domain/name/since/limit/companies are all already documented, including 'domain preferred' and the 10-item batch cap. The description largely restates the batch semantics rather than adding new meaning; baseline 3 applies.

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

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

States a specific verb and resource — a dated change feed of a competitor's was→now strategic shifts, newest-first — plus a batch mode. This clearly separates it from siblings like list_competitor_moves (undated list) and get_pricing_changes (narrower vertical).

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 opening 'Use when the user asks what changed, what's new, or wants a timeline' gives an explicit trigger condition, and the batch paragraph explains when to use `companies` instead of domain/name. It stops short of naming when to prefer a sibling (e.g., get_pricing_changes or list_competitor_moves) instead.

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 openWorldHint=false, so safety is covered; the description adds real value beyond them by enumerating the return payload (hub fields, deduped player list, market_news with narrative/topics/momentum/sources) and disclosing the negative case { covered: false } for untracked markets. It does not discuss data freshness beyond 'latest weekly' or any rate/coverage limits, keeping it short of a 5.

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

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

Front-loaded with the trigger condition and return contents, but the 'whole-category map, not a self-selected competitor set' idea is stated twice in near-identical wording ('every player in it, not just a self-selected competitor set' and again later), which is pure redundancy in an otherwise compact paragraph.

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

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

With no output schema, the description carries the return-value burden and does so fully: hub contents, deduped player fields, the market_news structure, and the not-covered sentinel. Combined with the discovery pointer to list_markets, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% and the schema already specifies slug-exact vs name-ILIKE matching with an example. The description only restates 'a vertical slug or name'; its useful addition (pointing to list_markets for slugs) is routing guidance rather than parameter semantics, so the baseline 3 applies.

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

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

States a specific verb and resource ('returns the published category overview plus every player') and explicitly distinguishes itself from the sibling family by contrasting the whole-category map with 'a self-selected competitor set' (i.e., find_competitors). An agent can route to it without opening the schema.

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

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

'Use when the user wants an overview of a whole market/category' gives an explicit trigger, and 'Use list_markets to discover slugs' routes to the prerequisite tool. It stops short of naming find_competitors or get_comparison as the alternatives for narrower questions, so the exclusion is implied rather than stated.

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false; the description adds real value on top by enumerating the returned fields and disclosing the coverage limit ('spans the markets IndustryLens publicly tracks') and the source of truth (changes 'IndustryLens has detected'). It does not mention detection lag or data refresh cadence, which would matter for a 'recent changes' feed.

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?

Use condition is front-loaded and the three calling modes are covered compactly. The closing sentence ('No other public source exposes structured competitor pricing-diffs like this') is marketing boilerplate that does not help an agent decide or invoke.

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, and the description compensates by listing the return fields and the shape of the batch response. Coverage limits are disclosed. Minor gap: nothing describes how far back the dataset actually goes or whether results are paginated beyond `limit`.

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

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

Schema coverage is already 100%, so the baseline is 3; the description earns a bump by clarifying the mutually exclusive semantics of `competitor` vs `competitors` and by noting one feed per company returned in input order with `since`/`limit` applied to each entry. Most of that restates the schema, but the exclusivity and ordering emphasis is useful for a batch call.

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

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

States a specific verb and resource — returns structured pricing/packaging changes with change_type, severity, materiality score, summary, and detection date — so an agent knows exactly what it gets back. It stops short of naming a sibling (e.g. get_competitor_moves_diff) to draw the boundary against, leaving that differentiation implicit.

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?

Opens with an explicit trigger ('Use when the user asks about a competitor's pricing/packaging changes, or wants a recent pricing-change feed') and then routes between the three calling modes: single competitor, market-wide feed, or batch list. No when-not-to-use condition or named alternative tool is given, so the sibling boundary remains unstated.

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 and openWorldHint=false, so the description carries the burden of disclosing real behavior, and it does: pdf_url is always null, PDF access is lead-gated behind a work-email form and client-side rendering, and no fetchable PDF bytes exist. This prevents a very likely agent failure mode that no annotation or schema field would reveal.

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

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

The purpose and gating caveat are front-loaded, which is good, but the PDF discussion runs long and includes meta-commentary ('verified live: the marketing_reports.pdf_url column is unpopulated... an earlier version of this description incorrectly claimed...') that documents the description's own history rather than helping the agent act. A trimmer version could convey the same constraint in two 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?

There is no output schema, so the description must explain returns, and it names the structured fields, content_html as the canonical body, the web URL, and the null/gated PDF fields. For a one-parameter read tool this is complete enough to call correctly and to answer follow-up user questions.

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

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

Schema description coverage is 100% and the single slug parameter is already documented with examples, so the schema does the heavy lifting. The description restates the slug requirement but adds no format or normalization detail beyond what the schema provides — the correct baseline of 3.

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 ('Fetch the full body of a published report by slug') and explicitly distinguishes itself from list_reports, which is named as the way to obtain the slug. An agent can select this tool without opening the schema.

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

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

Opens with an explicit trigger ('Use when the user wants the full text of one published IndustryLens report') and states the prerequisite workflow ('after finding its slug via list_reports'). It also says what not to do ('Never construct or guess a .pdf URL yourself'), which is a concrete exclusion.

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

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

Annotations already cover the safe-read profile (readOnlyHint=true, openWorldHint=false), so the description adds what they cannot: each result carries a slug usable with get_comparison, and the URL pattern for constructing links. It does not mention default page size or pagination in prose, but the limit param is clear in schema.

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

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

Four short sentences with the when-to-use clause front-loaded and zero filler. Slightly dense but each sentence (usage, filter, slug, URL) carries distinct information, so nothing is wasted.

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

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

No output schema exists, and the description compensates by telling the agent what each item contains (a slug) and how to use it with get_comparison, plus the canonical URL form. For a simple two-param read-only list tool, nothing an agent needs is missing.

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

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

Schema coverage is 100%, so baseline is 3; the description adds a small but useful nuance by reiterating that the competitor filter matches either side, and by framing the whole listing as optionally filtered. It doesn't explain ILIKE/substring semantics beyond the schema, keeping it just above baseline.

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

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

States a specific verb and resource ('browse published competitor-vs-competitor breakdowns') and immediately distinguishes itself from the sibling get_comparison by contrasting browse-listing against slug-fetch. An agent can route between the two without opening either schema.

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

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

Explicitly names the when ('user wants to browse... or find one involving a specific competitor') and the when-not ('rather than fetch one specific comparison by slug'), pointing to the alternative tool by slug. Also documents the optional filter's matching behavior.

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

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

Annotations only cover read-only and closed-world; the description adds substantial behavioral context beyond that: newest-first ordering, what each record contains (existence of the shift, was→now summary, real analysis date), a guarantee against fabricated dates, and two distinct empty-state semantics ('covered: false' vs. an empty list). That is exactly the kind of edge-case disclosure an agent needs.

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

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

Three sentences with zero filler; the usage trigger is front-loaded, followed by return shape and then edge cases. Every clause carries information the agent would otherwise have to guess.

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

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

No output schema exists, so the description must explain return values — and it does, covering ordering, per-record fields, and both empty-result variants. For a two-parameter read tool with read-only annotations, nothing material is missing.

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

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

Schema description coverage is 100%, including the default/max for limit and the name-or-domain format for competitor, so the schema carries the parameter burden. The description reinforces the single-competitor framing but adds nothing about limit behavior or result truncation. Baseline 3 applies.

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

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

States a specific verb and resource ('Returns recent tracked strategic moves for one competitor') with explicit scoping to a single competitor and newest-first ordering. The singular-competitor scope cleanly separates it from siblings like get_competitor_moves_diff and get_comparison without needing the 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?

Opens with an explicit trigger: 'Use when the user asks what a specific competitor has recently done or changed.' That is clear usage context, but it offers no exclusions or named alternatives (e.g., pointing to find_competitors when the competitor is unidentified, or to the diff tool for comparisons).

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 openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: results are ordered by name and each item exposes a slug — useful because no output schema exists. It stops short of saying how large the list is or whether it is paginated/cacheable, 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 short sentences with zero waste: trigger first, return shape second, linkage to the follow-on tool third. Every sentence carries distinct information and the most decision-relevant clause is front-loaded.

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

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

With no output schema, the description must describe the return value and does: a name-ordered list of markets, each with a slug consumable by get_market_landscape. Combined with annotations covering read-only behavior and a zero-parameter schema, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4 and the description correctly avoids inventing any input semantics. Nothing is promised about arguments that could mislead an agent.

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

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

Names a specific verb and resource (list the markets IndustryLens tracks), scopes it to B2B SaaS categories, and explicitly distinguishes it from the sibling get_market_landscape, which it points to for the full map. An agent can tell exactly what it returns and what it does not.

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

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

Opens with an explicit trigger ('Use when the user wants to know which markets... or needs a slug for get_market_landscape'), naming both the intent and the downstream dependency. That is a clear when-to-use plus a named alternative for the full category map, so the routing decision needs no inference.

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

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

Annotations already cover the safety profile (readOnlyHint=true, openWorldHint=false), so the bar is lower; the description still adds real context by disclosing result ordering (newest-first), the shape of each item (carries a slug), and the canonical URL pattern. It stops short of stating a default result count or pagination behavior, which the schema partly covers via the limit parameter.

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

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

Four tight sentences, front-loaded with the usage trigger and scoping, then ordering, then chaining guidance, then URL format. The URL sentence is the least essential but still earns a place by letting the agent construct links without a follow-up call.

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

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

No output schema exists, yet the description tells the agent what a returned item contains (a slug) and how to chain to get_report, plus ordering and URL shape. Combined with annotations covering safety and full schema coverage on parameters, an agent has everything needed to call and consume this tool.

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

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

Schema description coverage is 100%, so both filters, the limit bounds, and default are already documented with examples. The description repeats that you can filter by industry or target_role but adds no syntax, matching behavior, or combination semantics beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource (browse/discover published competitive-intelligence reports) and immediately delineates scope from the sibling get_report by contrasting 'browse or discover' with 'fetch one specific report by slug'. An agent can route correctly without opening either schema.

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

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

Opens with an explicit 'Use when' condition and names the alternative (get_report by slug) plus the disambiguating factor. It also hints at discovery axes (topic, role, industry) that map to the available filters, so the agent knows which call to make and how to narrow it.

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

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

Annotations already declare this is a write (readOnlyHint=false), non-destructive, and non-idempotent; the description adds valuable context beyond that — a confirmation is returned and the source value is persisted for attribution. It does not cover what happens on duplicate subscriptions (relevant given idempotentHint=false) or failure modes, which keeps it below a 5.

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

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

Three short sentences, zero waste, with the consent constraint front-loaded before the mechanics. Every sentence carries distinct information.

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

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

For a two-parameter write tool with no output schema, the description covers the consent prerequisite, the effect, the return value, and the meaning of the optional argument. Nothing an agent needs in order to call it correctly is missing.

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

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

Schema coverage is 100% and the schema already documents both fields, including the 'mcp' default for source. The description restates the default and attribution purpose but adds no syntax, format, or edge-case detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Signs the given email up' to a named newsletter — and the result ('returns a confirmation'). No sibling tool in the list does anything similar (all others are read-only competitive-intelligence queries), so the tool is unmistakable.

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

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

Gives an explicit precondition with a hard exclusion: 'Use ONLY after the user explicitly asks... never subscribe an email without their direct, informed consent.' This is about as clear as usage guidance gets for a side-effecting tool.

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