IndustryLens

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

With no annotations, the description carries the behavioral burden and does add real value: it discloses that results are limited to companies IndustryLens tracks and that the response is '{ covered: false }' for untracked companies. It omits auth, rate-limit, and ordering/pagination behavior, so it is informative but not exhaustive.

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, led by the 'Use when...' trigger, then the operation, then the edge-case return. Zero filler, though the timing/return sentence could be slightly tightened.

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

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

For a three-param, zero-required read tool with no output schema, the description covers the trigger, the input form, and the notable 'covered: false' return case. It leaves the full response shape (fields per competitor, ordering) unstated, which is a minor gap rather than a blocking one.

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 name, domain, and limit are already fully documented, including the 'domain preferred' hint. The description only echoes that input may be a domain or name, adding nothing 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?

The description states a specific verb and resource: it returns 'the other companies IndustryLens tracks in the same market' for a given company. That is clear and concrete, but it does not differentiate from siblings like get_competitive_profile or get_market_landscape, which an agent could easily confuse for this task.

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 asks who else competes in a company's market, or wants a peer/competitor set' gives a clear triggering condition. It stops short of naming when NOT to use it or which sibling to pick for adjacent needs (e.g., market landscape vs. competitor set).

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?

No annotations are provided, so the description carries the full burden, and it does disclose the shape of what comes back (content_json with pricing, recent moves, positioning, displacement signals, when-to-choose, plus metadata). It implies a read-only fetch but says nothing about auth requirements, rate limits, or what happens for an unpublished or missing slug — a meaningful gap for a lookup keyed on 'published' comparisons.

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, usage condition front-loaded, with the fetch and return details following in a sensible order. The first sentence ('full head-to-head detail') and second ('full structured body') overlap slightly, so it is efficient but not waste-free.

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 describe the payload and it does so well by enumerating the content_json sections. With no annotations, some behavioral context (failure modes for bad/unpublished slugs) is still missing, but the definition is otherwise sufficient 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% and the single slug parameter is already documented as coming from list_comparisons, which the description merely echoes. No additional format, validation, or edge-case meaning is added 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 (fetches) and resource (the full structured body of a published competitor comparison by slug), and clearly scopes it as the single-comparison detail view versus the list. An agent can distinguish it from list_comparisons and the other get_* siblings without opening any schema.

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

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

Begins with an explicit trigger ('Use when the user wants the full head-to-head detail for one published comparison') and routes the agent through the prerequisite sibling, naming list_comparisons as the source of the slug. The when-to-use condition and the alternative are both spelled out.

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

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

With no annotations provided, the description carries the full burden and does so richly: it discloses that unenriched firmographic fields read `collected: false` with a 'not yet collected' note rather than a guess, that moves include a real analysis date, that untracked companies return { covered: false }, and that batch entries are order-preserving and status-tagged. These are non-obvious data-freshness and coverage behaviors an agent could not infer from the 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?

Front-loads the trigger conditions before the payload description, which is the right ordering for an agent deciding whether to call. It is dense and runs long in its parenthetical field list, but nearly every clause carries actionable information rather than filler.

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

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

No output schema exists, so the description must describe returns — and it does, covering the profile contents, the covered:false case, and batch status tags. For a 3-param, annotation-less read tool, an agent has everything needed to call it 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 baseline is 3, and the description edges above it by adding semantics the schema lacks: the mutual exclusivity rule ('Omit domain/name when using this'), result ordering ('in the order given'), and the per-entry `status` value set (account / public / not_covered / ambiguous). The maxItems 10 and domain-preference hints are largely restatements of the schema.

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

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

States a specific verb+resource with concrete triggers ('who competes with a company', 'what a competitor recently did', 'competitive overview of one or more domains') and spells out the returned payload (firmographics, recent strategic moves, report links). It stops short of naming how it differs from the sibling find_competitors, whose apparent purpose overlaps with the first trigger phrase.

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 triggers tied to user utterances, plus a clear batch condition ('Pass `companies` instead of domain/name to look up several companies in one call'). It never states when NOT to use it or routes the agent to alternatives like find_competitors, get_market_landscape, or get_comparison, so sibling selection remains partly inferred.

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?

No annotations are provided, so the description carries the full burden. It discloses ordering (newest-first), date fidelity (real analysis dates, never fabricated), the { covered: false } fallback with a CTA, and batch semantics — substantial behavioral context. It omits auth/permission needs and any rate 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-loads the trigger condition then details the return shape and batching. Dense with em-dashes and parentheticals, and the 'never a fabricated date' clause leans promotional, but each sentence conveys usable information.

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

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

With no output schema and five parameters, the description supplies the return shape, the covered:false case, and the batch/multi-competitor behavior. It stops short of describing the individual move fields, but is otherwise sufficient to call 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 baseline is 3, but the description adds real meaning: domain/name selection guidance, and the batch contract for `companies` (per-entry result blocks, input order preserved, since/limit applied to every entry). That goes beyond what the schema states.

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

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

States a specific verb and resource: returns the dated was→now change feed for one competitor, newest-first. It is clearly distinguishable from siblings like get_pricing_changes and list_competitor_moves by scoping to detected strategic shifts with real analysis dates.

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 trigger conditions ('when the user asks what changed, what's new, or wants a timeline'). It does not name sibling alternatives (e.g., against get_pricing_changes or list_competitor_moves), so routing is implied rather than fully specified.

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 no annotations, the description carries the burden and does disclose substantial behavior: it enumerates the exact return shape (hub, deduped players, market_news), and crucially states the sentinel { covered: false } for untracked markets. Read-only nature is implied by 'returns' but not stated explicitly, and no permission/rate details are given — a minor gap.

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

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

Front-loads the trigger well, but the 'every player in it, not just a self-selected competitor set' idea is repeated twice (once in the usage clause, again after 'whole-CATEGORY map'), which is redundant. The long return-shape sentence is informative but dense.

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 describe returns — and it does thoroughly, listing hub fields, player fields, and market_news contents, plus the not-covered case. Everything an agent needs to call and interpret the result is present.

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 description already explains the slug-or-name matching (ILIKE, with examples). The description restates 'a vertical slug or name' without adding syntax beyond the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource (returns a whole-category market map) and explicitly distinguishes itself from siblings by contrasting 'the whole-CATEGORY map, not a self-selected competitor set' — implicitly vs find_competitors. An agent can route correctly without opening schemas.

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

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

Opens with 'Use when the user wants an overview of a whole market/category' and names the alternative condition (a self-selected competitor set). Also routes to list_markets for slug discovery, so both when-to-use and a sibling alternative are explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses the return payload (change_type, severity, materiality score, summary, detection date), notes that the date is the 'real detection date', and states the coverage limit ('markets IndustryLens publicly tracks'). It omits auth/permission requirements, rate limits, and pagination behavior, so not a full 5.

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

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

Front-loaded with the usage trigger, then scoping, then return shape — a sensible order with no wasted sentences, though the closing 'No other public source exposes...' line is promotional rather than operational.

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

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

No output schema exists, and the description compensates by describing the returned fields and their meaning, plus scope limits and default behavior. For a 4-parameter, zero-required read tool, an agent has everything needed to call it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains the scoping decision (pass `competitor` for one company, omit for a feed) and the batch semantics ('each in input order', with `since`/`limit` applying to every entry). That is real value beyond the schema text.

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

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

States a specific verb+resource ('Returns structured pricing/packaging changes IndustryLens has detected') and enumerates the returned fields, making the scope concrete. It never names an alternative sibling (e.g. get_competitor_moves_diff or list_competitor_moves), so an agent must infer differentiation itself, which keeps it out of 5 territory.

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 clearly routes between the single `competitor` scope and the batched `competitors` scope. No exclusion criteria or when-not-to-use guidance is given, so it falls short of a 5.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that pdf_url is always null, that the PDF is gated behind a work-email lead capture and rendered client-side, and that no fetchable PDF bytes exist anywhere. It also warns against a concrete failure mode (constructing or guessing a .pdf URL), which is exactly the kind of non-obvious behavior 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?

The purpose and routing are front-loaded correctly, but the middle section is bloated with meta-narrative — a live-verification note about the marketing_reports.pdf_url column and an admission that an earlier description version was wrong. That changelog detail serves maintainers, not the calling agent, and the no-PDF point is restated more than once.

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

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

There is no output schema and no annotations, so the description must describe the return shape and the operational traps; it does both, naming content_html, the web URL, pdf_url, and pdf_download.url. Nothing an agent needs to call this correctly or to advise the user afterward 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 gives the slug format with two concrete examples, so the baseline is 3. The description adds sourcing context by tying the parameter to list_reports output, which meaningfully reduces the chance of passing an unvalidated slug.

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 — 'Fetch the full body of a published report by slug' — and enumerates what comes back (structured fields, content_html, web URL). It is immediately distinguishable from list_reports, which it explicitly positions as the slug-discovery step.

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 the triggering condition ('Use when the user wants the full text of one published IndustryLens report') and the prerequisite ('after finding its slug via list_reports'). It also defines the boundary case — the PDF is not obtainable through this tool, so the agent must redirect the user rather than call something else.

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 no annotations, the description carries the burden, and it delivers: results are restricted to published comparisons, each item carries a slug that composes with get_comparison, and URLs follow a stated pattern. It does not disclose ordering or whether results are paginated beyond the limit parameter, which is the remaining gap for a list 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?

Three tight sentences: the use condition leads, the cross-tool slug hint follows, and the URL pattern closes. Nothing is repeated across sentences and every clause is actionable.

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 rightly sketches the return shape (slug-bearing items) and the URL convention, which is enough to call and chain the tool. Ordering of results and behavior past the limit cap remain unspecified, a minor gap for a two-optional-parameter list endpoint.

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 limit (default 10, max 50) and competitor (matches either side, ILIKE). The description restates the either-side matching already in the schema and adds no format or syntax detail beyond it, 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 (list) and resource (published competitor-vs-competitor comparisons) and explicitly contrasts its scope with get_comparison's single-by-slug fetch. An agent can distinguish it from siblings 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 to browse ... rather than fetch one specific comparison by slug" gives both the trigger condition and the named alternative (get_comparison). The optional competitor filter is also framed as a browsing aid, so the when-to-use path is unambiguous.

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

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

With no annotations, the description carries the full burden and discloses ordering ('newest-first'), return structure ('existence of each shift plus a was→now summary'), a data-quality guarantee ('real analysis date, never a fabricated date'), and two edge cases ({ covered: false } for untracked companies and an empty list for covered ones with no moves). This is unusually thorough behavioral disclosure for a read-only list 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?

Three tight sentences, front-loaded with the usage trigger and followed by return details and edge cases. No filler; each sentence adds routing or behavioral value.

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 lacking an output schema and annotations, the description explains the return shape, ordering, and edge cases well enough for correct invocation. Nothing critical is missing for a two-parameter read-only list 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% with both parameters documented, so the baseline is 3. The description adds no parameter-specific information (e.g., acceptable competitor formats or limit semantics) beyond what the schema already provides.

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

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

The description opens with an explicit trigger ('Use when the user asks what a specific competitor has recently done or changed') and states the returned resource ('recent tracked strategic moves for one competitor'). It does not, however, distinguish this list view from sibling tools such as get_competitor_moves_diff or get_pricing_changes.

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 a clear when-to-use scenario tied to a user request about a specific competitor's recent changes. It does not name alternatives or state when not to use this tool (e.g., when diffing moves or when looking at pricing changes).

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?

No annotations are provided, so the description must carry the behavioral burden, and it does: it discloses the return ordering (by name) and that each item carries a slug. It stops short of describing result size or any limits, but for a zero-parameter read-only lister this is solid disclosure.

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

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

Three short sentences, all front-loaded with the use case first. The slug is mentioned twice, which is mild redundancy, but no sentence is wasted.

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

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

With no output schema, the description must characterize the return value, and it does (list of markets, name-ordered, each with a slug). It does not note whether the list is exhaustive or paginated, a minor 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?

The tool takes no parameters, so the baseline is 4. The description correctly describes no input and instead explains the output field (slug) the caller will consume.

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

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

States a specific verb and resource ('list the markets IndustryLens tracks') with scoping that names the domain (B2B SaaS markets/categories). It is clearly distinguishable from siblings like list_reports or list_comparisons, 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?

Explicitly names the trigger ('when the user wants to know which markets are tracked, or needs a slug for get_market_landscape') and routes the agent onward to get_market_landscape for the full category map. When-to-use and the alternative are both 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?

With no annotations present, the description carries the full burden and delivers useful behavioral facts: results are ordered newest-first, each item exposes a slug, and URLs follow a known pattern. It does not mention pagination behavior or any auth/permission requirements, so it stops short of full disclosure.

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

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

Three sentences, all front-loaded: usage trigger first, then filtering and ordering, then the return/URL shape. No sentence is redundant and the most decision-relevant information leads.

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 3-parameter, zero-required list tool with no output schema, the description covers the usage trigger, the filters, ordering, and the shape of returned items plus a usable URL pattern. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents limit, industry, and target_role in detail. The description only restates the two filters ('Filter by industry or target_role') without adding syntax or format detail beyond the schema, matching the baseline 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 precise verb+resource ('browse or discover published competitive-intelligence reports') and scopes it as list/browse behavior. It explicitly contrasts itself with fetching 'one specific report by slug', which maps directly to the sibling get_report.

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 wants to browse or discover... rather than fetch one specific report by slug' gives an explicit when-to-use and when-not-to-use, and names the alternative tool (get_report) that handles the excluded case.

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

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

With no annotations, the description carries the full burden and does well: it discloses the consent precondition, that a confirmation is returned, and that the source argument is recorded for attribution with a default. It omits lower-priority traits like rate limits or unsubscribe behavior, but the mutation's safety-relevant behavior is covered.

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, no filler, and the critical consent constraint is front-loaded before the mechanical description of what it does. Every clause earns its place.

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

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

For a simple two-parameter mutation with no output schema, the description supplies the consent gate, the return behavior, and the parameter rationale. It stops short of stating what the confirmation contains or error conditions, but nothing essential for correct invocation is missing.

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

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

Schema coverage is already 100%, establishing a baseline of 3, and the description adds genuine meaning: it explains the purpose of source (recorded for attribution) and its default value, which the schema only states tersely.

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 (subscribe/signs up) and resource (the email address for IndustryLens's weekly newsletter), and makes the resulting confirmation explicit. An agent can immediately tell this apart from the read-oriented sibling tools like get_report or list_reports.

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 conditions use: 'Use ONLY after the user explicitly asks' and 'never subscribe an email without their direct, informed consent.' This is a clear when-to-use gate that goes beyond mere context.

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