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

Annotations already declare a safe read (readOnlyHint/idempotent/destructive=false), yet the description adds substantial behavior: the citation contract and WITHHELD-claim rule, the four status values (ready/partial/withheld/not_generated) with their meanings, Pro-plan 403 PLAN_REQUIRED, and 404 tenant isolation. This is far beyond what structured fields convey.

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

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

Front-loads purpose before the args and return contract, and the verbose status enumeration earns its place given there is no output schema. It is longer than strictly necessary, but most sentences carry decision-relevant detail rather than padding.

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 fully documents the return shape (status, sections_empty/locked, withheld_reason, markdown, source/report_id) and the error paths (403, 404). Nothing an agent needs to call and interpret this tool is missing.

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

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

Schema description coverage is 100% and the single parameter is already documented as 'Competitor UUID from list_competitors'. The description repeats that same hint ('from list_competitors') without adding format or sourcing detail, so the baseline 3 for fully-covered single-param tools 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 ('Get the cited sales battlecard for one tracked competitor') and enumerates the four content sections, so the agent knows exactly what artifact is produced. The 'cited' qualifier plus the withheld-claims clause distinguishes it from generic intelligence siblings like get_competitor_intelligence.

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 trigger phrases ('give me sales ammo against <competitor>', 'how do we win vs <competitor>', prepping a call), giving clear context for selection. It does not, however, name an alternative tool or state when NOT to use it, so it stops short of full when/when-not/alternatives guidance.

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

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

Annotations already cover read-only/idempotent/non-destructive, so the bar is lower, and the description still adds real disclosure: history is never synthesized, stored weeks exist only for Pro accounts, the return includes an 'honest tracking-start date', and long Markdown is paginated with each page naming the next call. Return-format and gating behavior are thus visible, though rate limits and failure modes are unstated.

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

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

Purpose and the 'Use when' trigger are front-loaded and the block structure is scannable, but the four-item Args section duplicates schema descriptions almost verbatim (week, format, page, project_id), so several lines do not earn their 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?

There is no output schema, so the description carries the return-value burden and does so reasonably: coordinates, trailing signal counts, momentum, latest headlines, importance source, available weeks, and tracking-start date. Pagination semantics are also covered, leaving only edge cases like empty/absent weeks unspecified.

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

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

Schema coverage is 100% and all four parameters are already described in the schema, so the baseline of 3 applies. The Args block largely restates the schema; its only marginal additions are the cross-reference to availableWeeks and the instruction to call list_projects first for the id.

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 ('Get') plus a precisely scoped resource ('current or stored weekly competitor positions on activity × strategic importance'), which separates it from siblings like get_competitor_intelligence, get_battlecard, and get_strategic_timeline. An agent can tell what it produces 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?

Explicit trigger phrases are given ('who is the biggest moving threat?', 'who moved most this month?') along with prerequisites ('Call list_projects first for the id') and a tier gate ('History requires Pro; the current view remains available below Pro'). It stops short of naming which sibling to use instead when the question is not about movement.

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

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

Annotations already cover the read-only/idempotent safety profile, but the description adds real behavioral context they don't: a 404 on cross-tenant access, the meaning of null/absent fields ("not measured" vs "none"), and that unverified claims withheld in the source report are withheld here too. This materially changes how an agent interprets results.

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

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

Front-loaded with the one-line purpose, then Args/Returns/Use-when blocks that are easy to scan. The Returns block is long but earns its space given there is no output schema; minor redundancy between the Args block and 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?

With no output schema, the description carries the return contract itself and does so thoroughly: field list, source enumeration (snapshot/report/none), a pointer from source_report_id to get_report, and null semantics. An agent can correctly call and interpret this tool from the description alone.

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 competitor_id as the UUID from list_competitors, so the description's Args block largely restates it. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

States a specific verb+resource ("get the latest stored intelligence for one tracked competitor") and scopes it to a single tracked entity. It explicitly distinguishes itself from the richer sibling by noting get_report is the fuller narrative.

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

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

Gives a concrete trigger phrase ("what's the latest intel on <competitor>?"), a prerequisite (find the id via list_competitors), and names the alternative (get_report) with the condition that selects it. Nothing is left to inference.

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

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

Annotations already cover the read-only/idempotent/open-world safety profile, and the description adds substantial behavior beyond that: unverified claims are withheld, corrected values are shown corrected, unlinked_attributions and off_entity_withheld are counted but not listed and no URLs are invented, and an empty sources array with an explanatory note is returned when no report is readable. The 404 semantics are also spelled out, including the deliberate indistinguishability of another account's competitor.

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

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

Front-loaded with the core purpose, then structured Args and Returns sections. It is long and dense, but with no output schema the return-format detail largely earns its place; a couple of parenthetical explanations (e.g. the stock-page example) could be trimmed.

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 no nested objects, the description carries the full burden of return-value documentation and does so thoroughly: the wrapper shape, each Source field, the withheld-count semantics, and the null-report case are all covered. Nothing an agent needs to call or interpret this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond the schema by stating the competitor must belong to the same project and by routing the agent to list_projects and list_competitors for valid IDs, including the cross-account 404 consequence.

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

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

States a specific resource and scope: 'the sources behind the facts for ONE subject: your own product (omit competitor_id) or one tracked competitor.' An agent can distinguish this from get_report, get_competitor_intelligence, and get_battlecard without opening schemas, and the subject-selection mechanism is 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?

Provides explicit 'Use when' triggers ('where does that come from?', 'show me the sources for <competitor>'s pricing', citing a claim) and clarifies when to omit competitor_id. It does not name a sibling alternative for when a full report or battlecard is wanted instead, but the positive usage context is clear.

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?

Goes well beyond the annotations (which already cover readOnly/idempotent/non-destructive) by disclosing that reading is free and 'this never fetches anything,' that no date is ever estimated or backfilled, that edit times are never treated as observation dates, that failed crawls / rejected reports / baseline copies are not observations, and that a 404 is returned for out-of-account projects. This is unusually rich behavioral disclosure.

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

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

Front-loads the purpose, then Args, then Returns, then Use-when, so an agent can extract what it needs quickly. The Returns block is lengthy, but with no output schema it earns much of its space; a few clauses (observation kind taxonomy) are 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?

With no output schema, the description carries the full burden and does so thoroughly: it enumerates the return shape, each competitor field, the observation-kind semantics, the status enum values, and the error behavior. Nothing an agent needs to call and interpret this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds workflow value by specifying the parameter is 'the project's UUID' and instructing the agent to call list_projects first for the id. It adds a small amount of meaning beyond the schema.

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

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

States a specific verb and resource ('how current your Rivalize data is for one project') and defines the exact scope: latest report date plus, per competitor, the date last observed and by what means. This is distinguishable from siblings like get_evidence or list_reports, which return content rather than freshness metadata.

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 ('how fresh is this data?', 'when did we last look at <competitor>?', before relying on a figure) and a prerequisite ('Call list_projects first for the id'). It does not name an alternative tool or state when NOT to use it, keeping it just 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?

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), yet the description adds real behavioral context: fabrication-flagged claims render as '[removed — unverified]' and must not be filled in, a bad section name errors and lists available sections, paging kicks in above 25,000 chars at section boundaries with 'Page N of M' headers and a next-page call, and a 404 is returned when the report is out of scope.

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?

Information-dense and front-loaded (return format first, then args, then routing examples), and the nested arg list is easy to scan. It is nonetheless long, and a few statements restate each other (whole-report default behavior, Markdown return format) — minor redundancy rather than padding.

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

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

No output schema exists, so the description carries the return contract itself: Markdown, section-per-competitor layout, citation/removal markers, page headers with remaining characters and the next-page call. Combined with the error and paging semantics, an agent has everything needed to call it correctly and interpret the result.

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%, but the description adds meaning the schema cannot: the full section vocabulary including both whole-report sections and per-competitor gathered sections (pricing, momentum, ads, tech-stack), the interaction rule that 'section + competitor' returns only that competitor's part of the section, case/spaces/underscore normalization ('Key findings' = key-findings), and that absent sections are an error listing what exists.

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 and resource ('Read one competitive-intelligence report as Markdown') and enumerates the actual content shape (TL;DR, biggest threat, blind spots, competitor sections, battlecards). It is clearly distinguishable from sibling list_reports, which it explicitly references as the source of report_id.

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

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

Ends with an explicit 'Use when:' block mapping real user questions to parameter combinations ('summarise my latest report' -> no section or tldr; 'what do competitors charge?' -> section pricing; 'what did the report say about <competitor>?' -> competitor). It also tells the agent when to narrow to a section (size: several thousand to 100k+ chars, a section ~1/6) and when to page.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds rich operational context: pagination splits at lane/move boundaries above 25,000 chars with 'Page N of M' and the exact next call, plan gating (Pro for full history/all competitors; lower plans limited to one competitor for 30 days), and the no-backfill-before-tracking limit.

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

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

Well front-loaded: purpose, then Args, then Returns, then usage triggers, so the most important framing comes first. Some redundancy exists between the Args block and the schema, but each section still carries distinct 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?

No output schema exists, and the description compensates by describing the return shape (structured events, seven-day move clusters, tracking-since dates, evidence URLs) and format switching. Combined with the plan limits, backfill caveat, and pagination contract, an agent has everything needed to invoke 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 description coverage is already 100%, so the schema fully documents all six parameters; the Args block largely restates them. The description adds minor nuance (markdown 'compact' vs json 'full structure') but does not meaningfully extend the enum/type information the schema already supplies. 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 ('Get a receipt-linked timeline of competitor activity') plus the exact lanes covered. An agent can distinguish this arc/timeline view from siblings like get_competitor_intelligence, get_battlecard, or get_freshness 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?

Provides explicit trigger questions ('what strategic moves have competitors made this quarter?', 'show the arc behind recent competitor activity') and a prerequisite ('Call list_projects first for the id'). It lacks any when-not guidance or named alternatives among the many sibling intelligence tools, which keeps it 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?

Annotations already declare read-only/idempotent/open-world safety, and the description adds substantial behavior beyond them: server-side domain normalization, the inverse relationship between requested layers and items per layer, capping of long arrays with _capped kept/total counters, and _omitted layers paired with the exact call that recovers them. It also guarantees the returned JSON is always complete and valid, which matters for an open-world lookup.

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 purpose, then Args, Returns, and Use-when in a predictable order with no filler prose. The Args block partly restates the schema, but it earns its place by adding normalization and layer-tradeoff details; the length is justified by the tool's breadth.

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 full burden of describing return shape and it does so concretely (top-level data keys, capping, omission protocol, validity guarantee). Combined with the domain/layer semantics and the sibling fallback, an agent has everything needed to call it correctly and interpret the result.

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, but the description adds real semantics: domain accepts a bare domain or any URL on it and is normalized server-side, and the layers filter is described behaviorally ('asking for fewer layers returns more items of each') rather than just listed. That is genuine value above the schema's enum list.

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

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

Opens with a specific verb+resource+scope ('Get the universe profile for one company by domain') and immediately enumerates the intelligence layers covered, which cleanly separates it from get_report, get_battlecard, and get_competitor_intelligence. An agent can route to 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?

The 'Use when: give me everything Rivalize knows about <domain>' line states clear usage context, and the description names fallback siblings (get_competitor_intelligence / get_report) for the not-tracked case. It stops short of an explicit when-not-to-use statement against the other sibling lookups, so it is strong but not exhaustive.

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/idempotent/non-destructive, so safety is covered; the description adds genuinely new behavioral context beyond them — tenant isolation, the pagination protocol (offset = next_offset until null), the 'deferred' state that causes the tool to retry before answering, and the fact that threat_level is a band of momentum_score rather than an independent assessment.

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

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

Well organized under Args/Returns/Use when headings and front-loaded with the core purpose, but it is long for a list tool and the brief.state enumeration is heavy detail for this surface. Some text (limit 'page size 1-100') duplicates the schema verbatim, and the decisive 'Use when' block sits last rather than up front.

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 carry the return contract, and it does: full JSON shape, the fields each Competitor carries, and how to page through results. It also pre-empts the trickiest ambiguity — how to compute a 'top' competitor and what to do when brief.state is not 'read'. Complete for the tool's call pattern.

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 still adds meaning: project_id is not just a filter but requires calling list_projects first for the id, and offset carries an implicit default of 0. The limit text merely restates the schema's '1-100', so the gain is modest but real.

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

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

Opens with a specific verb and resource plus a scope qualifier: 'List the competitors tracked in YOUR Rivalize account (tenant-isolated)', and frames the question it answers. This cleanly separates it from sibling list_universe_companies, which covers a different (untracked) population.

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?

Ends with an explicit trigger list ('which competitors am I tracking?', 'who is my top competitor?', 'before any per-competitor read') and routes to specific siblings by scenario: get_competitor_intelligence, get_battlecard, get_evidence, list_reports/get_report, get_freshness. Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), so the description's marginal value comes from the return contract: it enumerates the Project fields and shows how the returned id chains into six named downstream tools. It does not mention pagination or result limits, which is the only meaningful gap for a list endpoint.

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

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

Front-loaded with the purpose, then returns, then usage — a sensible ordering. Nearly every line earns its place, though 'Args: none.' is redundant filler given the empty 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 carries the return contract itself and does so by naming every returned field plus the id's downstream use. Combined with the explicit usage triggers, an agent has everything needed to select and call 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?

The tool takes zero parameters, so there is nothing to document beyond the explicit 'Args: none.' Baseline for a no-parameter tool is 4; there is no ambiguity for an agent to 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?

States a specific verb and resource ('List the projects in YOUR Rivalize account') and then defines the domain term 'project' as a product plus its tracked competitors, which disambiguates it from the similarly named list_competitors sibling. An agent can distinguish this tool 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?

Gives explicit trigger phrasings ('what products/projects do I have?'), states the precedence rule ('first, whenever another tool needs a project_id'), and names the competing alternative ('For which competitors am I tracking? use list_competitors'). When-to-use, when-not, and alternatives are all present.

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, idempotentHint and destructiveHint=false, but the description adds non-derivable facts: reads are free, it never generates a report, and quick-depth reports leave certain fields blank and 'Needs full research' rather than being findings. That last point is real interpretive context that prevents an agent from misreading the payload. It does not cover rate limits or auth scope, so not a 5.

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

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

Front-loaded purpose sentence, then clearly sectioned Args, Returns and Use when blocks. The Report field enumeration is long but justified because there is no output schema; nothing reads as filler. Slightly heavy for a list tool, keeping it from a 5.

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

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

With no output schema, the description carries the return-shape burden and does so: it documents the JSON envelope, pagination fields, per-report fields, status values, and the depth distinction. Combined with the 'Use when' routing, an agent has everything needed to call and interpret 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 coverage is 100%, so the baseline is 3, but the description adds workflow meaning the schema lacks: project_id requires first calling list_projects for the UUID, and limit/offset are framed as page size and pagination offset with defaults restated. The uuid/format and bounds detail lives in the schema and is not duplicated.

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 competitive-intelligence reports'), adds scope ('in YOUR Rivalize account'), ordering ('newest first'), and explicitly disclaims report generation, which separates it from generation/teardown siblings. An agent can distinguish it from get_report or get_battlecard without opening a schema.

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

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

Provides an explicit 'Use when' trigger with two concrete query phrasings, states the prerequisite for project_id ('Call list_projects first for the id'), and routes the follow-up ('Use the returned id with get_report'). Both the entry condition and the alternative for single-report retrieval are named.

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/idempotentHint/openWorldHint, so safety is covered; the description goes further by disclosing truncation behaviour ('_truncated', reduced 'returned'), the pagination continuation rule (always advance with pagination.next_offset, null means done), unnamed defaults for limit/offset that the schema omits, and the slug-vs-name matching pitfall. It stops short of error/auth behaviour, but for a read-only list endpoint this is well above the annotation baseline.

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

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

Purpose and sibling routing are front-loaded, then args, then return shape, then usage triggers — a clean, scannable structure. It is somewhat long and the Args block duplicates most of the schema's own parameter descriptions, though each entry carries a small increment (defaults, slug caveat) that justifies keeping it.

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

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

There is no output schema, and the description fully covers the return contract: the compact JSON envelope, pagination fields, the per-Company field list including the 120-character description cap, and the truncation continuation rule. Combined with the sibling routing, an agent has everything needed to call and paginate this tool correctly.

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

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

Schema coverage is 100%, so the baseline is 3, and the description genuinely adds meaning on top: it warns that category values are slugs and that display names such as 'AI infrastructure' do not match, and it supplies the defaults (limit 50, offset 0) that the schema does not encode. It largely restates the q/layer parameter prose, but the slug caveat and defaults are real added value.

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

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

States a specific verb and resource (list companies from the Rivalize universe) and immediately disambiguates it from the sibling that could be confused with it: 'not your own tracked competitors; for those use list_competitors.' An agent can pick between list_universe_companies, list_competitors, and get_universe_company 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?

The description names both the exclusion condition ('not your own tracked competitors') and the replacement tool (list_competitors), plus explicit trigger phrasing ('who are the players in <category>?' / 'show me universe companies matching <keyword>') and a hand-off to get_universe_company for single-entity lookups. Nothing about when to reach for this tool is left to inference.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial behavior beyond them: output is Markdown not raw JSON, results are dated/lead with refresh time, ads count as active only if seen in the last 30 days, and unscored momentum is labeled as not scored. These are genuine operational traits the agent could not infer from 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 core capability, then a routing sentence, args, and return/edge-case notes. It is longer than a minimal description but every block earns its place; minor density in the final caveat sentence keeps it from a 5.

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

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

With no output schema, the description carries the return-value burden and does so: it specifies Markdown format, freshness dating, the 30-day active-ad rule, unscored momentum handling, and the not-in-universe fallback. An agent has everything needed to call this correctly on the first try.

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 there is a single required 'domain' param, so the schema already documents it fully. The description restates 'domain or any URL on it' and the required status, adding marginal value over the structured field. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource (produce a full strategy teardown of one competitor by domain) and enumerates the exact contents (positioning/hooks, pricing, ads, social, reviews, hiring, momentum, weaknesses). It explicitly distinguishes itself from the ad-only teardown and names the sibling tools it defers to, so an agent can tell it apart without opening any schema.

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

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

Gives explicit invocation phrasing ('tear down <competitor>', 'what is <competitor>'s strategy and where are they weak?') and states it is the broader one-call option vs an ad-only teardown. It also routes the not-yet-in-universe case to get_competitor_intelligence / get_report, naming concrete alternatives.

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