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

Annotations only declare readOnlyHint=false and openWorldHint=false; the description adds substantial context the annotations cannot: the entry is attributed to an API key rather than a person, the thread is capped at 500 entries, and a read_write key is mandatory while read keys are refused. These are real behavioral facts that affect invocation.

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, front-loaded with purpose, followed by attribution and constraint details. No filler, and each sentence carries information an agent needs before calling the tool.

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

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

For a mutation tool with no output schema, the description covers auth requirements, capacity limits, and attribution semantics, which is nearly everything needed. It does not address failure behavior beyond the read-key refusal (e.g., what happens at the 500-entry cap), leaving a small gap.

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

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

Schema coverage is 100% and each parameter (projectId, ticketId, body) is documented in the schema, including that body is Markdown. The description restates the Markdown format but adds no syntax, format, or length guidance beyond what the schema already provides, 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 and resource ('Add an entry to a ticket's thread') and immediately qualifies the artifact type (Markdown) and attribution. An agent can distinguish this from the sibling list_ticket_comments or create_ticket 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?

The description implies usage via the auth constraint ('Needs a read_write API key; a read key is refused and can only list and read'), which tells the agent not to attempt this with a read-only key. However, it never explicitly says when to add a comment versus updating or moving a ticket, so routing guidance is only 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?

Annotations only cover readOnlyHint/openWorldHint, but the description layers on substantial behavioral detail: the unreadable-robots.txt failure mode returns NO verdict, 'permitted' is explicitly not 'cited', modelTrainingAccess is neutral and must not be reported as a gap, and there is a mechanical exception when a token appears in both decidedByCrawlers lists. This is exactly the kind of context annotations cannot carry.

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 is front-loaded in the first clause and each subsequent sentence carries a distinct anti-misreporting rule, so little is wasted. It is dense and long for a 2-param read tool, but the length is paying for interpretation that the missing output schema would otherwise have provided.

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 return-value burden and does so: it names assistantAccess, decidedByCrawlers, modelTrainingAccess, userAgentToken, ruleAudience, and robotsTxt.read, plus the empty-verdict case. An agent has everything needed to call it and interpret the response correctly.

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

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

Schema description coverage is 100% and both parameters (domain, industry) are documented there, including the enum values for industry. The description adds nothing about either parameter (industry is never mentioned), 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+resource+mechanism: 'Live check of which AI ASSISTANTS can fetch a site's pages, read from its robots.txt.' That is a precise enough scope (robots.txt-derived AI assistant fetch access) to separate it from siblings like check_sitemap, fetch_url, or get_ai_visibility_dashboard 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 bulk of the description is interpretation guidance (how to read assistantAccess, modelTrainingAccess, ruleAudience) rather than when-to-use routing. No alternative tool is named and no exclusion condition or prerequisite is given, so usage is only implied.

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

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

Annotations only declare a safe read of an open world; the description adds substantial behavior beyond them — deduplication across /sitemap.xml and robots.txt-declared sitemaps, the two distinct causes of status: 'partial', and that only the unreadSitemaps cause reflects a site defect. This is exactly the kind of context an agent cannot 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?

Purpose is front-loaded and every sentence carries interpretive weight, but the partial-status and programmatic-category explanations are dense and somewhat verbose for a description. Efficient overall, with minor room to tighten.

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 itself — status semantics, unreadSitemaps, category definitions, and where sample URLs live (insights.sampleUrlsByCategory). An agent has what it needs to call and correctly interpret the 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 parameters are already documented, including that sitemapUrl short-circuits discovery. The description adds no additional parameter syntax or format 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?

The first sentence gives a specific verb+resource+scope: 'Live sitemap analysis for any domain — discovers URLs, categorizes them by section, and reports depth, freshness, and per-category counts.' It is instantly distinguishable from siblings like check_ai_crawlers or fetch_url.

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 is rich on how to interpret results but never states when to reach for this tool versus alternatives, nor any exclusions. Usage is implied by the domain-scan framing rather than stated explicitly.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries the real behavioral load and delivers: the 5,000-ticket cap and refusal past it, new tickets landing at the top of the column, labels being refused if not on the project list, labels not creatable from here, the fixed column set, and the API-key attribution that marks automation-created tickets.

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

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

The description is long but front-loaded and dense with operational facts; every clause (cap, ordering, refusal conditions, auth) informs correct invocation. Minor redundancy in restating the column set and the label creation caveat, but no filler.

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

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

With 9 parameters, no output schema, and thin annotations, the definition supplies enough to call it correctly, including the auth requirement and refusal conditions. It does not describe the returned ticket shape, but that is a modest omission given the breadth already covered.

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 beyond the schema: it explains why status has no default, what each column value means, and that labelIds must come from the project's own list (list_ticket_labels) or the call is refused.

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?

Starts with a specific verb and resource: 'Open a ticket on a project's board.' This is clearly distinguishable from sibling tools like update_ticket, move_ticket, and add_ticket_comment, which each imply a different operation on an existing ticket.

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?

Explains the preconditions for calling it: title and status are both required, status has no default, and a read_write API key is needed (a read key is refused). It does not explicitly contrast with update_ticket or move_ticket, but the create-versus-modify boundary is implied by the opening sentence.

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

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

Annotations already flag destructiveHint=true, and the description adds substantial context beyond that: irreversibility ('cannot be undone'), a hard exclusion case, the refusal behavior, and an auth requirement (read_write key required; read key refused and limited to list/read).

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

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

Front-loads the destructive warning in the first two short sentences, then layers exception, precondition, and auth. Dense and mostly waste-free, though the mid-sentence rationale ('so that what opened it does not open it again') is slightly verbose.

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 2-parameter destructive mutation with no output schema, the description covers the essential caveats: irreversibility, exclusion case, prerequisite check, and API key requirements. Nothing an agent needs to invoke it safely 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% with only 2 parameters, both fully documented in the schema itself (ticketId accepted as ID or '#14', projectId). The description adds no parameter-level syntax or constraints, 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 and resource ('Delete a ticket and its thread'), and immediately notes the scope includes the thread. It differentiates from the sibling move_ticket by naming it as the alternative path for the excluded case.

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

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

Explicitly covers when-not-to-use: a ticket opened by a Strategic Briefing cannot be deleted and must be moved to dismissed via move_ticket. It also states a precondition (read 'deletable' on the ticket first) and the consequence of ignoring it (refusal).

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 and openWorldHint, so the safety profile is covered. The description adds substantive behavioral context beyond that: JS-rendering, partial failure under advanced fingerprinting, and the headersAvailable:false branch signal. It stops short of covering rate limits or redirect behavior, but the failure-mode disclosure is genuinely useful.

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 tightly written sentences that front-load the core capability before the caveat and the return summary. Dense but every clause carries information; no filler or repetition.

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

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

There is no output schema, so the description carries the burden of naming return fields; it does so (body, headers, cleanStats) and explains the headersAvailable edge case. For a 6-parameter read tool this is close to complete, with only minor gaps around pagination or error shapes.

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 every parameter is already documented in the schema, including the cleanHtml/bodyNeeded dependency and the headersAvailable branching rule. The description restates the cleanHtml token-cost benefit but adds no syntax or semantics the schema lacks, so the baseline of 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 ('Fetch any URL') and immediately layers on differentiating capabilities (automatic JS-rendering, bot-protection handling) that go beyond a tautological restatement of the name. No sibling tool performs URL fetching, so no confusion risk exists and an agent can select it unambiguously.

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

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

Usage is implied by the description (fetching arbitrary web content for LLM consumption), but there is no explicit when-to-use/when-not-to-use statement and no named alternative, even though check_sitemap and check_ai_crawlers are network-adjacent siblings. The agent can infer the intended context but is given no routing rules.

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 and openWorldHint, so the safety profile is covered. The description adds meaningful behavior beyond that: the tool returns different payload shapes depending on run state and should be polled at a 5-10 second interval. It stops short of describing result contents or failure states.

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, front-loaded with the core action, and the polling recommendation lands last where an agent will find it. Sentence two partially restates sentence one's status-retrieval idea, a small redundancy.

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

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

There is no output schema, so the description must characterize return values, and it does distinguish the running-status response from the completed-results response. This is adequate for a one-parameter polling getter, though it says nothing about error or expired-scan behavior.

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

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

With a single parameter at 100% schema coverage, the schema already carries the format detail (the 24-char hex pattern and the 'from start_agent_adoption_scan' origin note). The description restates that lookup is by scanId but adds no new syntax or constraint information, 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 and resource ('Retrieve status or full results of an Agent Adoption Check by scanId'), which clearly separates it from the sibling start_agent_adoption_scan without needing to name it. It is not tautological and conveys the retrieval role precisely.

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?

Explains when in the lifecycle to call it ('while running' vs 'when finished') and gives a concrete polling cadence of 5-10 seconds, which is real operational guidance. It does not explicitly name the alternative tool for launching a scan, so it falls short of full when/when-not coverage.

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?

Far beyond the readOnlyHint/openWorldHint annotations, it discloses RETRIEVED-never-cited semantics, three distinct answer states that are 'never merged,' the meaning of a missing vs empty sources key, answersTruncated behavior, rank provenance, and error-state distinctions (run_not_summarized vs check_not_found vs invalid_check_id). It also quantifies response sizes (30,000-70,000 chars) and cost.

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

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

The leading sentence front-loads the core purpose, then bulleted rules follow, which suits a 12-parameter tool with no output schema. Some content is dense and mildly redundant (answer-state semantics appear in the intro block and again in the includeAnswers schema text), but the structure is purposeful and every rule 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?

For a complex, 12-parameter, annotation-thin, no-output-schema tool, the description covers return-value semantics, attribution rules, sizing limits, filtering, and error states comprehensively. An agent has everything needed to call and interpret it without guessing.

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 view, engine, includeAnswers, includeSummary, paging limits, and their interactions in depth; the description largely echoes those constraints ('view=full returns every row'). It adds cross-parameter guidance such as narrowing with engine/promptIndex, but does not materially exceed the schema's parameter documentation. Baseline 3 is appropriate.

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

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

The first sentence states a specific verb+resource and scope: 'One AI Sources check (checkId, not runId),' returning its stored summary and, with includeAnswers=true, raw answers plus retrieved pages. It explicitly distinguishes itself from siblings by keying on checkId rather than runId and by referencing get_ai_sources_dashboard for the shape.

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

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

It gives clear routing: use engine= or promptIndex= to narrow a large answer read, prefer those over fetching everything, and set includeSummary=false with includeAnswers=true when you already hold the summary. It also names get_ai_sources_history as the source of checkId and get_ai_sources_dashboard for the summary reading rules. It stops short of explicit when-not-to-use exclusions beyond the size warnings.

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 only safety (readOnlyHint=true, openWorldHint=false), yet the description discloses rich semantics: retrieved-never-cited, per-engine-never-pooled counts, counts-not-rates, 'not measured is never zero', verdict as a condition code, and concrete response-size ranges (30k-70k compact, 250k-450k full). It also flags that cost is dominated by page lists and that answer text is unverified third-party engine output.

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

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

The purpose is front-loaded, but the body is a dense multi-bullet memo roughly 2,500 characters long, mixing calling guidance with output-interpretation rules. Much of it earns its place given the absence of an output schema, but it is heavier than an agent needs to select and invoke the tool.

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

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

For a 10-parameter, no-output-schema tool with heavy paging and per-engine structures, the description covers scope, cost, paging behavior, engine/prompt narrowing, and the readingGuide fallback. Nothing an agent needs to call it correctly appears to be 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 baseline is 3. The description reinforces the compact/full paging split and clarifies that coreHosts[] carries pageUrls rather than page rows, but most of its parameter detail (brandsOffset, pagesHost, engine) restates what the schema already documents.

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

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

The opening states a specific verb and resource: which pages Perplexity and Google AI Overviews retrieved for this project's buying questions, which companies each named, and which pages omit the customer. It is clearly a source-retrieval dashboard rather than the citation-oriented get_ai_visibility_dashboard, though that sibling contrast is implied rather than named.

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

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

It gives conditional guidance: omit view for the default, use view=full for every row (paging then refused), and 'Prefer engine= or promptIndex= over fetching everything' because of cost. There is no explicit statement of when to pick this tool over get_ai_sources_history or get_ai_visibility_dashboard, which keeps it below 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 only supply readOnlyHint and openWorldHint, and the description goes far beyond them: it discloses the checkId-vs-runId identifier model, the truncated size-cap behavior (whole rows dropped, hasMore does not account for them), that absent engines mean 'not measured, never zero', that only published checks appear (abandoned checks never publish), and that figures are counts not rates. This is exactly the kind of non-obvious behavioral context 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?

Front-loads the purpose and is free of filler, with each sentence carrying a usage or interpretation rule. It is dense and slightly repetitive (the per-engine universe point is made twice), and the run-on final block is heavier than necessary, but given the semantic complexity it stays close to appropriately sized.

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, yet the description fully specifies the return shape (each row carries per-engine measured figures and a funnel from core hosts to missing hosts) plus pagination and truncation semantics. For a history tool with no structured output definition, nothing an agent needs in order to interpret results 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 real meaning beyond the schema by tying the limit parameter to truncated behavior ('lower limit rather than paging forward') and explaining what pagination.hasMore does and does not reflect. It does not restate or clarify the projectId pattern, but the added limit/truncated interplay lifts it 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 ('Get paginated history of AI Sources checks') and immediately nails the unit of the dimension ('the unit of this dimension is a check, one cycle of every buying question against every engine'). It distinguishes itself from get_ai_sources_check_detail, which it explicitly routes to, so an agent can tell the two apart 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 clear routing to a sibling ('Pass a row's checkId to get_ai_sources_check_detail for its full summary') and a concrete when-not for pagination ('lower limit rather than paging forward' when truncated). It does not, however, contrast itself against get_ai_sources_dashboard for current-state vs historical use, leaving one obvious alternative unaddressed.

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 readOnlyHint/openWorldHint, yet the description discloses costs (20,000-30,000 char summaries, ~1,500 chars per brand entry), truncation behavior (answersTruncated drops whole prompts), the three never-merged query states, and attribution rules for model prose. These are behavioral traits far beyond the annotations.

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

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

Purpose and the three query states are front-loaded, and most sentences carry unique operational payload. It is long and repeats the three query states in both the top prose and the includeAnswers description, but the density of real constraints justifies most of the length.

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 in detail: summary.competitorRankings, marketMap paging, answers block growth, unansweredQueries, noAnswerShown, answersTruncated, and readingGuide as the fallback for unlisted fields. 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 goes further by explaining the cost model that sizes includeAnswers, the interaction rules (brand/provider/promptIndex require includeAnswers; paging requires summary), and why score vs mentionRate means 'below top 5' rather than 'never named'. Only slightly redundant with the already-detailed schema.

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

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

Opens with a precise verb+resource and immediately disambiguates the identifier type ('checkId, not runId'), plus names the sibling tools get_ai_visibility_dashboard and get_ai_visibility_history for context. An agent can distinguish this from the dashboard/history/run_detail 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?

Explicit routing: narrow with brand/provider/promptIndex before fetching answers, use summary.customer.perPrompt before pulling raw answers, and includeSummary=false when the summary is already held. It also names the alternative read paths (get_ai_visibility_dashboard semantics) and gives when-not conditions (paging refused with includeSummary=false).

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

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

Beyond the readOnlyHint annotation, it discloses payload cost (20,000-30,000 chars compact, 113,000 full), the paging_requires_compact_view refusal, attribution limits ('unverified model output... never as fact'), and a dense set of null/absence semantics (null rankByPresence means not named, absent provider means not asked). This is exactly the behavioral context annotations cannot carry.

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 payload summary is front-loaded and the numbered rules are scannable, but the description is very long and folds a whole interpretation manual into the tool doc. Most sentences earn their place for an agent, yet it is not tight.

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

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

With no output schema, the description carries the full burden of explaining return shape and hazards, and it does: field meanings, null semantics, absence-vs-not-mentioned distinctions, cost scaling, and a pointer to readingGuide for unlisted rules.

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

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

Schema description coverage is 100%, so the baseline is 3. The description reinforces the brand and mapLimit semantics and the includeAnswers cost model, but those are already spelled out in the schema, so it adds little meaning beyond structured fields.

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

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

The opening sentence names a specific verb-resource pair and enumerates the payload: market map, mention rates, scores, per-model breakdowns, competitor rows. 'Latest' implicitly distinguishes it from get_ai_visibility_history and get_ai_visibility_trend, but no sibling is named outright, so an agent must infer the boundary rather than read it.

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

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

The description gives strong operational guidance: read summary.promptMarket first, then lead with the market, prefer the brand/provider filters over fetching everything. This is mostly about how to consume the response rather than when to pick this tool over get_ai_visibility_history, so it stops short of the top band.

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

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

Annotations only cover the safety profile (readOnlyHint, openWorldHint=false), so the description carries the rest and does: only scored checks appear, checks published before the coverage gate may be scored over fewer answers than asked, absent promptMarket is an unproducible reading rather than a pass, and truncated true means whole entries were dropped from the end (lower limit). These are exactly the non-obvious behaviors an agent would otherwise get wrong.

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 is front-loaded in sentence one and the rest is broken into scannable bullets, each covering a distinct decision (score vs mentionRate, promptMarket, truncated, pagination, totalEntries). It is dense and longer than ideal, and some row-field semantics arguably belong to the detail/trend tools, but nearly every sentence earns its place.

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

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

There is no output schema, so the description must explain the return payload, and it does thoroughly: score/mentionRate meaning, per-row summary fields, promptMarket, truncation and pagination signals. An agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so page, view, limit and projectId are already documented in the schema, including the compact/full character budgets and the truncated/limit interplay. The prose adds framing (why to lower limit) but no parameter semantics beyond what the schema states, 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 opening states a concrete resource ("a page of scored AI Visibility checks") and immediately disambiguates the identifier model ("uses checkId, not runId"), which tells an agent this is a listing/history tool rather than the run-oriented siblings. It stops short of a clean verb and doesn't name the sibling endpoints (get_ai_visibility_check_detail, get_ai_visibility_trend) it competes with, so differentiation relies on inference.

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 routes the agent explicitly: read summary.totalEntries before pulling the heavier get_ai_visibility_check_detail payload, and use summary.customer.perPrompt to answer "which prompt am I losing on" without another call. It also gives exclusion-style rules (never call a listed check fully covered; never say the prompts are wrong), leaving little to inference.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds extensive behavioral context beyond that: it explains what 'move' means, how nulls are treated, when to call a rise or fall (presenceChangeSeparable), what enginesBacking implies, and how to report incomplete cycles. These rules are critical for correct interpretation and are not available in the annotations or schema.

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

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

The description is long but structured with bullet points and front-loads the core purpose. Given the tool's complexity and the absence of an output schema, most sentences earn their place by specifying required interpretation rules. It is dense but not redundant.

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 fully explain return values and semantics. It covers field semantics (presenceChange, rankChange, scoreChange), event handling (standingChanges, incompleteCycles, promptsLastChangedAt), window quoting, null treatment, and enginesBacking. This is comprehensive for a tool of this complexity.

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

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

Schema description coverage is 100%, so all five parameters are thoroughly documented in the schema itself. The description adds no parameter-specific syntax or format details beyond what the schema provides; it focuses entirely on output interpretation. Baseline 3 is appropriate when the schema does the heavy lifting.

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

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

The description states a specific purpose: showing how the AI models' market moved over a window, who is recommended more or less, and whether the customer's standing changed. It distinguishes itself from get_ai_visibility_history by noting that the latter with limit=1 provides the latest check alone. An agent can identify the tool's scope 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?

The description implies the tool is for comparing movement across a time window, but it does not explicitly state when to use it versus alternatives like the dashboard or history endpoints. A single alternative is mentioned in passing (get_ai_visibility_history limit=1), but there is no general when-to-use or when-not-to-use guidance. The heavy interpretation rules are useful but not usage selection guidance.

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

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial behavior beyond that: meta.status state machine (done/running/failed/null), the two-hour completion window and the instruction to treat slow runs as running, null item semantics, and how tickets are counted live from the board. This is exactly the extra context the annotations cannot convey.

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

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

Front-loaded with the core purpose, but the body is long and repeats itself — the 'recommendations are tickets, not in item' point appears in both the description and the sections schema text, and several status branches are belabored. Much of the length earns its place for a stateful tool, but it is not tight.

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

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

No output schema exists, so the description carries the return-value burden, and it does so thoroughly: it explains item, meta.status, meta.progress, tickets (opened/commented/alreadyOnBoard/recheckedUnchanged) and contains. An agent has everything needed to call and interpret this correctly.

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

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

Schema coverage is already 100%, so baseline is 3, but the description adds real meaning beyond the schema: it explains why 'hub' is the default and cheap, how the response's `contains` array should be read instead of guessing, and that includeCharts=false yields titles with no numbers.

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 the current state of the project's Strategic Briefing') and immediately scopes it as the analyzed as-of read across 14 named analysis areas. It explicitly distinguishes itself from siblings by naming get_<dimension>_dashboard tools and list_competitors as the alternatives for live and roster data.

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

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

Gives explicit when-to-use guidance: defaults to 'hub' which 'answers most questions in one call', add sections only when needed, use get_briefing_history/get_briefing_edition on running or failed runs. It also names the counter-case ('NEVER tell the user no briefing is available on the strength of a null item').

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), and the description adds substantial non-obvious behavior: it mirrors get_briefing's shape and defaults, and crucially discloses that a runId for a failed or still-generating run returns successfully with meta.status set and item null — 'an answer, not an error.' It also explains the tickets counters (opened, commented, alreadyOnBoard, recheckedUnchanged) and the unmeasured-ticket edge case.

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

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

The core purpose and key routing (past vs current, tickets board) are front-loaded in the opening sentences, and the sentences are dense with distinct facts. It runs long, however, and the tickets explanation is partly restated inside the `sections` parameter description, so not every word is unique to this field.

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 four parameters, the description carries the full burden and does so: it describes the return shape ('same shape as get_briefing'), the run-status edge case, where recommendations actually live (tickets, not item), and how ticket state should be read. Nothing material an agent needs to call or interpret the result 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 per-parameter schema text is itself rich, so the baseline is 3. The description still adds semantic value: guidance to read the response's `contains` array rather than guess which sections exist, the note that sections are added only when the question needs them, and the warning that includeCharts=false omits underlying numbers. Much of the section vocabulary is duplicated from the schema, which keeps this from a 5.

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

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

States a specific verb and resource ('Get one past Strategic Briefing edition in full'), names the retrieval key (runId, from get_briefing_history), and explicitly contrasts itself with the sibling get_briefing ('For the current state use get_briefing'). An agent can pick 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?

Gives the exact trigger ('read or quote a specific past edition — including the last readable one when get_briefing reports a running or failed status') and the explicit alternative for the live case. It also routes the agent to the tickets board rather than the edition when the question is about follow-up actions.

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, but the description goes well beyond: it discloses the payload shape ('one cheap metadata row each — runId, publication date, edition number, status, headline verdict'), guarantees it 'NEVER' returns briefing content, and explains that failed/generating runs appear with null date and headline so gaps are interpretable. That is rich, non-obvious behavior an agent could not infer.

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

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

Front-loaded with purpose and scope, then routing and fallback guidance; every sentence carries usable information. It is longer than strictly necessary and the fallback rationale is somewhat repeated, but there is little waste.

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

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

With no output schema, the description carries the return-value burden and does so: it enumerates the metadata fields, states what is never returned, explains null-date rows for failed/running editions, and points to pagination.hasMore. Nothing an agent needs to call 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 description coverage is 100% (projectId, page, limit all documented in-schema), so the baseline is 3. The description adds only a pointer to pagination.hasMore rather than clarifying any parameter's format or defaults, so it does not meaningfully exceed 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 ('List this project's past Strategic Briefing editions, newest first') and explicitly delimits scope from siblings: it names get_briefing_edition as the follow-up and get_briefing as the tool for current state. An agent can distinguish it from every nearby sibling 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?

Explicit when-to-use with concrete examples ('what did we say in April', 'how has the read changed'), a named follow-up tool with its argument (get_briefing_edition with that runId), an explicit exclusion ('For the project's current state use get_briefing, not this'), and a fallback rule when get_briefing reports 'running' or 'failed'.

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 structurally. The description adds the shape of the returned data (monitored pages and their URLs), which is useful, but discloses nothing about pagination, permissions, or error behavior beyond what annotations provide.

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

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

Two short sentences, front-loaded with the return scope and followed by the ID-sourcing prerequisite. No redundant or filler text.

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 read with no nested objects and no output schema, the description plus 100%-covered schema is nearly sufficient; the added note about which fields are returned compensates for the missing output schema. Only minor gaps remain (no pagination or error semantics).

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

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

Schema coverage is 100% and both parameters already carry descriptions pointing to list_projects and list_competitors. The description's 'use competitorId values from list_competitors' merely echoes the schema, adding no format, constraint, or selection meaning beyond it. 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 (Get) and resource (competitor details) and names the payload it returns (monitored pages: homepage URL, pricing page URL). This distinguishes it from the sibling list_competitors, which only enumerates competitors rather than returning per-competitor detail.

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

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

Explicitly tells the agent where to source the required competitorId (from list_competitors), which is the key prerequisite for a correct call. It stops short of stating when-not to use it or naming a detail-vs-list alternative explicitly, so it falls 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?

Beyond the readOnly/openWorld annotations, it discloses pagination, the truncation flag and byte-cap behavior, the default 3-sample-URL return shape, and a crucial semantic caveat that per-sitemap add/remove rows can reflect re-filing rather than real activity. That last point is behavioral context no annotation or schema could convey.

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

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

Front-loaded with purpose and pagination/return behavior, then the caveat. The caveat paragraph is long and slightly repetitive ('loudest way to be wrong'), but every sentence carries decision-relevant weight, so only minor trimming is warranted.

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 thin annotations, the description still conveys return shape, pagination, truncation handling, and the analytical caveat an agent needs to report results correctly. Nothing material is missing for a 6-param read 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; the description adds real meaning on top by explaining the default vs. full-URL behavior of allUrlsPerCategory and the token-cost tradeoff of filtering. It does not add format detail for page/limit/projectId, so not a 5.

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

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

States a specific verb+resource ('Get detected content changes over time per competitor sitemap') and disambiguates from the many content-dashboard/history/run-detail siblings by naming the unit of comparison (per-sitemap). An agent knows exactly what this returns 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?

Explicitly says to filter by competitor/category to scope and to pass allUrlsPerCategory:true only when full URL lists are needed, plus a strong when-to-distrust-results rule. It does not explicitly name an alternative sibling (e.g., get_content_history) to route to instead, 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?

Annotations only declare readOnlyHint and openWorldHint=false; the description goes well beyond them, spelling out failure modes (contentAnalysisAvailable, 'no_sitemap_published' vs 'sitemap_fetch_failed'), which fields are null vs empty and why, and that competitors being unreachable must not be blamed on the customer. That is real behavioral context an agent cannot get from annotations. It does not cover permissions or refresh/caching behavior, so not a 5.

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

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

The purpose is front-loaded in the first sentence and each subsequent paragraph addresses a distinct ambiguity (null vs empty, the two failure causes, the 9 assessed categories vs the unassessed ones, the two opposite-signed gap fields, per-row reasons). It is dense and reads as prose rather than scannable structure, but very little is 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 no output schema, the description carries the full burden of explaining the return payload, and it does so thoroughly: null-vs-empty semantics, the two distinct causes of missing data, the polarity of gapPercentage vs strategicUrlGap, and which categories are never assessed. For a single-parameter read tool, an agent has everything needed to 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?

There is a single projectId parameter with 100% schema description coverage (including the source list_projects and a 24-hex pattern), so the schema fully documents it. The description adds no format or sourcing detail beyond that. Baseline 3 is appropriate when the schema does all the work.

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

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

The first sentence states a concrete verb+resource: 'Latest Content Intelligence for every competitor' followed by the specific payload (sitemap URL counts, strategic URLs, categories, sitemap structure, gap analysis). It is immediately clear what the tool returns. However, it never distinguishes itself from the very similar siblings get_content_history and get_content_run_detail, so it falls short of a 5.

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

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

The description gives heavy guidance on how to READ the result but never says when to call this tool versus get_content_history or get_content_run_detail. Usage is only implied by the purpose statement. There are no exclusions or alternative-selection cues, so this lands at the minimum-viable level.

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 readOnlyHint and openWorldHint, so the description adds real value: it explains how to paginate via pagination.hasMore and, critically, the interpretation rule that a null means an unreadable sitemap and never a measured zero. That semantic warning prevents a serious misreading of 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?

Three short sentences, front-loaded with the core purpose, then pagination mechanics, then the null-semantics caveat. Every sentence earns its place with no filler or repetition.

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

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

For a read-only listing tool with no output schema, the description supplies the two things an agent most needs: how to page through results and how to interpret null values. It stops short of characterizing what each run record contains, but the essential calling information 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 description coverage is 100%, with page, limit, and projectId all documented including defaults, bounds, and provenance (from list_projects). The description adds no per-parameter detail, so the baseline of 3 is correct when the schema carries the load.

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 paginated history of Content Intelligence monitoring runs." That clearly separates it from get_content_run_detail (single run) and get_content_dashboard (current state), though it never names those siblings explicitly. The scope is unambiguous without opening the schema.

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

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

It implies usage (fetching the run history) and gives operational instructions for pagination, and it references get_content_dashboard for the reading rule. But it never states when to prefer this over get_content_run_detail or get_content_changelog, so the agent must infer the selection boundary.

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 far beyond the readOnlyHint/openWorldHint annotations: it explains that every tracked competitor appears even when unmeasurable, defines the contentDataAvailable.reason values, prescribes how to phrase findings, and distinguishes 404 run_not_summarized from run_not_found. This is exactly the behavioral detail an agent needs to avoid misreporting.

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 and the runId provenance before the interpretive rules, and every clause carries real guidance. It is dense and slightly repetitive around the sitemap/programmatic caveats, costing it the top mark.

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 delivers: it describes row structure, null-count handling, reason enums, and the error semantics. An agent has everything needed to read and report the response correctly.

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

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

Schema description coverage is 100%, so both runId and projectId are already documented at their source. The description reinforces where runId comes from but adds no format or constraint 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 ('Get full competitor-by-competitor data for a specific historical Content Intelligence run') and distinguishes itself from siblings by pointing at get_content_history as the source of runId and at get_content_dashboard for reading rules. An agent can tell it apart from the history and dashboard tools 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?

Explicitly routes the agent ('Use runId values from get_content_history') and binds the interpretation conventions to get_content_dashboard ('Same reading rule'). It gives clear context for invocation but stops short of stating when NOT to use it or why to pick this over the dashboard variant.

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

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

With readOnlyHint already covering the safety profile, the description goes well beyond annotations: it explains the null-propagation rule for a failed customer-homepage analysis, names messagingAnalysisAvailable as the reason field, and preserves the distinction between a measured empty string (a real finding) and a null (never read). It also documents that a null messaging gap is not a tie. That is genuinely useful behavioral context an agent cannot get from the annotations or 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-loaded with purpose and return contents before the edge-case rules. The null-vs-empty-string passage is dense and slightly repetitive ("including the headline and CTA strings"), but each sentence carries real information about interpreting the response, so it mostly earns its length.

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 full burden of describing return values — and it does, enumerating the messaging fields and explaining the null semantics of summary.customer and the messaging score/gap. An agent has what it needs to call the tool and interpret the response correctly.

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

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

Schema coverage is 100% and the single projectId parameter carries its own description with a pattern and provenance hint (from list_projects), so the schema does the work. The description adds no syntax or format detail about the parameter, which is the expected baseline-3 case for a fully documented single-parameter 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 ("Get the latest Positioning analysis for all competitors") and enumerates exactly what the resource contains — homepage messaging fields. The word "latest" plus "all competitors" implicitly separates it from get_positioning_history and get_positioning_run_detail, so an agent can pick 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?

Scope language ("latest", "all competitors") gives implied guidance that this is the aggregate snapshot rather than a per-run or historical view, which is enough for an agent to prefer it over the sibling history/run-detail tools. However, there is no explicit when-to-use or when-not-to-use statement and no named alternative, so the guidance stays implicit.

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 genuinely useful interpretive behavior beyond that: a null entry means an unanalyzable homepage, not a zero or empty result, which an agent cannot infer from the schema or annotations.

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

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

Three tight sentences with zero filler; the pagination cue and the null-semantics warning are each front-loaded and 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: it points to the dashboard's summary shape, gives a pagination signal (pagination.hasMore), and explains the null convention. The actual summary fields are deferred to another tool rather than spelled out, so it is strong but not fully self-contained.

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

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

Schema coverage is 100%, so page, limit, and projectId are fully documented in the schema with defaults and bounds. The description adds no additional parameter meaning, so the baseline of 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 paginated history of Positioning monitoring runs'), which distinguishes it from the dashboard-style siblings by making clear this is the run-history listing. It links explicitly to get_positioning_dashboard for shape, though it never mentions get_positioning_run_detail, so differentiation from all siblings is incomplete.

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 operational guidance on pagination ('Check pagination.hasMore to fetch additional pages'), which is a real usage instruction. However, it never says when to prefer this tool over get_positioning_dashboard or get_positioning_run_detail, leaving the selection context 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 establish readOnlyHint=true, so safety is covered, yet the description still adds substantial value: it defines the 404 run_not_summarized case versus run_not_found and prescribes how to report it (say the run produced no data, don't call it missing, don't zero-fill). That is exactly the kind of non-obvious behavioral detail structured fields cannot carry.

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 is front-loaded, followed by sourcing guidance and error semantics, with no padding. The sentence 'Same reading rule as get_positioning_dashboard' is a cryptic cross-reference that costs a lookup and doesn't fully earn its place on its own.

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 should hint at the return shape; 'full competitor-by-competitor data' gives a rough idea and error behavior is thoroughly covered. A brief note on the response structure would have closed the remaining gap, but nothing critical is missing.

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

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

Schema description coverage is 100% and both parameters are documented with their sources, so the schema does the heavy lifting. The description only echoes the runId provenance that the schema already states, adding no format or constraint detail beyond it.

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

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

Specific verb+resource: retrieve per-competitor data for a historical Positioning run. It distinguishes itself from get_positioning_history by directing the agent to that sibling only as a source of runId values, so the two tools are not confused.

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

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

Explicitly says to source runId from get_positioning_history and points to get_positioning_dashboard for the shared reading rule. It does not spell out when to prefer this over the dashboard or history tools, and the cross-reference adds a lookup burden, but the invocation path 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description adds substantial behavioral context the annotations cannot, e.g. that null means 'WE DID NOT CHECK', that pricingAnalysisAvailable gives the reason, and that hasPriceGap is null below three comparable prices. It stops short of any auth, rate-limit or freshness/latency disclosure, but the interpretation rules are genuinely valuable.

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

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

The purpose is front-loaded in the first sentence and the remaining dashes each carry a distinct interpretation rule rather than filler. It is long and dense for a single-parameter read tool, and some of it (e.g. repeated 'a null X is not Y' constructions) could be tightened, but with no output schema most sentences 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?

No output schema exists, so the description correctly carries the return-value burden and does it thoroughly: field meanings, null semantics, comparability rules and the pre-unit-grouping caveat are all covered. What is missing is any link to the run/history siblings or pagination/limit behavior, which leaves a small gap for an agent deciding where this fits.

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

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

There is a single required parameter (projectId) and schema description coverage is 100% with the schema itself stating 'Project ID (from list_projects)'. The description adds nothing about the parameter, which is the expected baseline when the schema fully documents it.

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

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

The opening sentence names the resource and its payload precisely ('The latest Pricing Intelligence for every competitor: up to 5 plans each ... market statistics, and the gap analysis'), which is a specific, inspectable outcome. It does not, however, name or contrast itself with obvious siblings such as get_pricing_history or get_pricing_run_detail, so an agent must infer from 'latest' that this is the snapshot rather than the trend.

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 text is almost entirely about interpreting returned nulls, not about when to select this tool over get_pricing_history, get_pricing_run_detail or get_positioning_dashboard. No preconditions, no 'use this when / use the sibling when' routing is offered, so the agent gets no selection guidance.

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

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses meaningful data semantics: a null means an unanalyzable run rather than zero, and null changes should not be read as competitive events. This is valuable interpretive context. It does not describe rate limits or output structure, but the added interpretation warrants a 4.

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 front-loaded sentences with essentially no waste: purpose first, pagination behavior second, then the reading rule. Slightly dense but every sentence earns its place.

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

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

With no output schema, the description compensates by explaining the pagination signal (pagination.hasMore) and how to interpret null fields, which an agent needs to call and read results correctly. It stops short of describing the full summary shape but references get_pricing_dashboard for that, which is reasonable.

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 each of the three parameters (page, limit, projectId) is fully documented in the schema. The description mentions pagination but adds no parameter syntax or format detail 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 (Get) and resource (paginated history of Pricing Intelligence monitoring runs), which cleanly separates it from siblings like get_pricing_dashboard and get_pricing_run_detail. An agent can identify its role without opening the schema.

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

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

The description implies usage by referencing get_pricing_dashboard's reading rule and explaining pagination with pagination.hasMore, giving practical fetch guidance. However, it never explicitly states when to choose this tool over get_pricing_run_detail or the dashboard, leaving the alternative selection 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?

Goes well beyond the readOnlyHint annotation by disclosing row-level behavior (every tracked competitor appears, unmeasured rows carry a pricingDataAvailable reason and null content) and precise error semantics (404 run_not_summarized means the run exists but has no data). It even instructs how to phrase results for that case, which is unusual and valuable for a read 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?

Purpose is front-loaded and every sentence carries information (provenance, row semantics, error semantics, output phrasing). It is dense and slightly cluttered with run-on sentences and a missing space ('row.A run'), but 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?

With no output schema, the description carries the return-shape burden itself: it explains that all competitors appear, how unmeasured rows look, and how to interpret the not-summarized error. Combined with the readOnly annotation, an agent has everything needed to call and interpret it correctly.

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

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

Schema description coverage is 100 percent and both params are documented inline (runId from get_pricing_history, projectId from list_projects). The description reinforces the runId source but adds no new syntax or format detail, so the baseline of 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 full competitor-by-competitor data for a specific historical Pricing Intelligence run'), clearly distinguishing it from get_pricing_history (list) and get_pricing_dashboard (dashboard). An agent can tell exactly what this returns 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?

Tells the agent where runId comes from (get_pricing_history) and cites a reading rule shared with get_pricing_dashboard, plus explicit error-handling guidance (404 run_not_summarized vs run_not_found). It lacks an explicit 'use this instead of X when Y' routing statement relative to dashboard/history siblings, but the 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?

Annotations already cover read-only/no-open-world safety, so the description instead invests in non-obvious data semantics: a timestamp only moves when a measurement is published, and neither an unchanged value nor null proves a cycle ran. That caveat is exactly the kind of behavioral context annotations cannot express.

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

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

Front-loaded with what is returned, then the usage trigger, then the caveat. The second sentence is long and dense but every clause carries new information (timestamp semantics plus two alternative tools); nothing is redundant.

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

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

With no output schema, the description carries the burden of describing return content and does so concretely: freshness per dimension, prompts, overall status, plus the interpretation caveat for timestamps. An agent has enough to call it and read the result correctly.

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

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

Single parameter with 100% schema description coverage — the schema documents projectId's format and even points at list_projects as the source. The description adds nothing about the parameter, so the baseline of 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 project details') and enumerates the returned content: per-dimension monitoring freshness across five named dimensions, AI monitoring prompts, and overall status. It clearly differs from list_projects (single project detail) and from the per-dimension dashboards, though it never explicitly frames itself as the 'single project' counterpart.

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 this to check when each dimension last produced data') and, for the ambiguous aiVisibility case, names the exact alternatives (get_ai_visibility_dashboard's latestCheckDataAvailable, get_ai_visibility_trend's events.incompleteCycles) with the condition that selects each. Routing is 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?

Annotations only declare readOnlyHint and openWorldHint; the description goes well beyond by explaining the partialDetection flag, why it appears (behavioral protection blocked response headers so hosting/CDN rules could not run), that listed detections are still real, and that totalTechnologies is a floor not a total. It also prescribes reporting behavior (never claim no CDN/managed hosting), which is exactly the kind of hidden-behavior disclosure that prevents downstream misinterpretation.

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?

It is front-loaded with the core purpose and return states before the partial-scan caveats, and the poll interval is placed last as a practical footnote. It is somewhat long, but every sentence addresses a real failure mode (misreporting partial results), so the length is largely earned.

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

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

With no output schema, the description carries the burden of explaining return values and it does so thoroughly: status while running, technologies with confidence when complete, and the meaning of partialDetection and totalTechnologies. Nothing an agent needs to call and interpret this tool correctly is missing.

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

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

Schema description coverage is 100% with a single required scanId parameter already documented with its pattern and origin. The description adds no extra syntax or format detail for the parameter, so the baseline 3 for schema-covered parameters 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 opens with a specific verb and resource ('Retrieve status or full results of a tech-stack scan by scanId') and states the two distinct return states (running status vs. detected technologies with confidence scores). An agent can immediately tell this is the polling/read companion to start_tech_stack_scan, whose name is echoed in the scanId param description.

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

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

It gives clear operational context (poll while running, results when complete) and an explicit recommended poll interval of 5-10 seconds, plus detailed rules for interpreting PARTIAL results. It stops short of naming alternative tools or stating when NOT to call it, but the usage context is concrete and actionable.

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; the description adds substantial context they cannot: null vs measured-zero semantics, the readingGuide field, aiAccess.measurement.status behavior, verbatim explanation rendering, and compact response size (~5,000 chars/competitor). It does not discuss auth, error modes, or 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?

Purpose is front-loaded in the first sentence, followed by a scannable bullet list of interpretation rules, and it explicitly defers remaining field rules to readingGuide rather than enumerating them all. It is long and dense, but nearly every line carries non-obvious data-semantics 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, the description carries the full burden of explaining returns, and it does so thoroughly: catalog structure, null semantics, per-field availability markers, AI access status, and the readingGuide escape hatch. The gap is the absence of explicit guidance on when this dashboard beats the sibling scans.

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 beyond the schema: view=full repeats the crawler catalog on every crawler item, while compact keeps tokens with a single crawlerCatalog and pages long lists. This clarifies what the enum choice actually changes in the payload.

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

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

The opening sentence names a specific resource scope ('Latest Tech & Trust Profile for every competitor') and enumerates the domains covered: security headers, trust signals, technology stack, AI access, DNS. An agent can tell it returns a per-competitor dashboard rather than a single-domain scan. It does not, however, explicitly differentiate itself from siblings like get_tech_stack_scan or get_trust_signals_scan.

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 is dominated by interpretation rules (null semantics, AI access status, trust-signal caveats) rather than when-to-use guidance. It never says when to prefer this dashboard over get_tech_stack_scan or get_trust_signals_scan, nor states prerequisites beyond referencing list_projects in the schema. Usage is implied by the resource name, but tool-selection guidance is absent.

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 nonetheless adds substantive semantics: null means unmeasured not zero, a null gap is not a tie, and present customer.securitySignalsAvailable means blocked headers with techStackCount acting as a floor. That is real interpretive context beyond the structured fields.

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

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

Front-loaded with the purpose in the first sentence, then pagination handling, then interpretation rules. Four sentences is long but each carries non-redundant guidance; nothing is 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 no output schema, the description must convey return shape, and it does: run summaries keyed to the dashboard's summary shape, pagination.hasMore, and the null/floor caveats. It stops short of a full field inventory, but the borrowed dashboard shape and caveats cover what an agent needs to read results correctly.

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

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

Schema description coverage is 100%, so page, limit, and projectId are already documented in the schema; baseline 3 applies. The description adds only the pagination.hasMore follow-up signal, not new syntax or defaults 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: 'Get paginated history of Tech & Trust monitoring runs,' plus what a row contains (run summaries with completion timestamps). It distinguishes itself from sibling get_tech_trust_dashboard (current snapshot) and get_tech_trust_run_detail (single run) by scope, even referencing the dashboard explicitly.

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

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

Usage is implied by the name and the 'paginated history' framing, and it tells the agent to check pagination.hasMore for more pages. But it never explicitly says when to pick this over get_tech_trust_dashboard vs get_tech_trust_run_detail, so routing is left to inference.

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

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

Annotations only cover readOnlyHint and openWorldHint; the description adds substantial beyond-schema behavior: the 404 run_not_summarized meaning vs run_not_found, that null security grades and robots.txt fields reflect blocked headers or fetch failure, and the aiAccess/technologyStack.partialDetection interpretation rules. For a read tool with no output schema, this is exactly the interpretive context that prevents misuse.

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

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

The purpose is front-loaded in the first sentence, followed by tightly scoped bullets that each prevent a specific misinterpretation. It is longer than typical, but nearly every line earns its place; density is high rather than padded.

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

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

With no output schema, the description carries the return-value burden and does so: it names the response shape, the error cases, and the null/partial-field semantics. Nothing an agent needs to call this tool correctly and report its output accurately is missing.

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

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

Schema description coverage is 100% and both parameters are documented there, so the baseline is 3. The description reinforces that runId comes from get_tech_trust_history, which mildly adds sourcing context but does not go beyond the schema in syntax or format.

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+scope: full competitor-by-competitor data for one historical Tech & Trust run. It also distinguishes itself from siblings by naming get_tech_trust_history as the runId source and get_tech_trust_dashboard as the shape it mirrors, so an agent can place 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?

It clearly routes the agent to get_tech_trust_history to obtain the runId and identifies the dashboard tool whose shape it matches, giving strong context for when this tool is the right one. It stops short of an explicit when-not/alternative clause (e.g. when to prefer the dashboard over a single run), so it is clear context rather than full routing.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, yet the description still adds substantial non-obvious context: cross-project IDs return 'not found' identically to nonexistent IDs, 'deletable' should be read before proposing deletion, briefing is null on non-briefing tickets, and effort/minutes are not derived from each other. This is exactly the behavioral disclosure annotations cannot carry.

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?

It is front-loaded and every sentence carries domain information, but it is a dense wall of text well beyond what a single-resource getter normally needs, bundling impact scales, briefing semantics, effort caveats, Markdown notes, deletion rules, and 404 behavior into one paragraph. The effort/'low ticket can be an afternoon' passage is the most rambling and could be tightened.

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

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

There is no output schema, so the description carries the full burden of explaining return values, and it does so thoroughly: impact's 1-4 scale, briefing's subfields (edition, analysis part, extendsTicketId), effort's nature, and error semantics. For a domain this intricate, nothing an agent needs to interpret the response is missing.

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

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

Schema description coverage is 100%, and both parameters (ticketId with its '#14' form, projectId from list_projects) are fully documented in the schema itself. The description adds no further syntax or format detail about the parameters, so the baseline 3 is correct.

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 one ticket') and immediately scopes the single-ticket granularity by enumerating exactly which fields come back, so an agent can distinguish it from list_tickets without opening a schema. The return-field inventory (description, labels, owner, due date, effort, impact, thread count) makes the tool's remit unambiguous.

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

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

Usage is largely implied by 'Get one ticket', and the only explicit routing hint is a narrow one: 'when a person asks for something quick, use maxMinutes on list_tickets'. That resolves a specific effort-vs-minutes confusion but does not say when to reach for get_ticket versus list_tickets, get_briefing_edition, or list_ticket_comments. Adequate but with clear gaps.

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, so the description carries the real behavioral load and does so richly: it explains the headerInspection {available: false} case, instructs that it is a fetch note and not a caveat, and defines null-vs-empty-array semantics so results are not misreported. This is exactly the kind of interpretation guidance the annotations cannot provide.

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

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

The purpose and return behavior are front-loaded in the first two sentences, followed by the caveats that earn their place given the absence of an output schema. The headerInspection/null passages are dense but each carries distinct, necessary interpretation rules 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 steps in to define the ambiguous result states (headerInspection marker, null fields, empty arrays) and the polling cadence, giving an agent everything needed to call and correctly report the scan. Nothing material is left unexplained.

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% (the single scanId param is documented, including its origin and pattern), so the schema already does the heavy lifting. The description adds no syntax or format detail beyond the schema, matching the baseline 3 for fully-covered parameters.

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

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

States a specific verb+resource ('Retrieve status or full results of a trust-signals scan') and names the keying parameter (scanId). It clearly pairs with the sibling start_trust_signals_scan and distinguises itself by covering retrieval/polling rather than initiation.

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 establishes the retrieval context ('current status while running', full results when complete) and gives a concrete polling cadence (5-10 seconds), which tells an agent how to use it as an async-poll tool. It stops short of explicitly naming start_trust_signals_scan as the prerequisite/alternative in the description body (only the schema does), and lists no when-not conditions.

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/openWorldHint, but the description adds substantial behavioral context beyond that: alerts are immutable ('written once and never revised'), numbers must be quoted as of createdAt, null 'before' is a measured absence rather than missing data, and zones are decided on a range not a point. This is exactly the kind of disclosure the safety annotations cannot carry.

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 tool-selection sentence is front-loaded and the filtering options follow compactly. The remaining bulk is dense output-interpretation guidance (alertType, standingChange, presence math) which, because there is no output schema, has to live here — though it reads as a run-on block rather than cleanly structured sections.

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 explain the return payload, and it does so thoroughly — alertType semantics, standingChange fields, presence ranges, and the immutability rule. Combined with read-only annotations, an agent has what it needs to call 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% with enums for severity and dimension already documented, so the schema carries the parameter semantics. The description restates the same filter values and adds little syntax or format detail beyond what the schema provides, 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?

Opens with a specific verb+resource ('Get paginated competitive alerts') and immediately scopes it ('detected changes across all monitored dimensions'), which cleanly separates it from the many get_*_dashboard and get_*_history siblings. An agent can tell this is the cross-dimension alert feed rather than a single-dimension dashboard.

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 details how to filter (dimension, severity, competitorId) and how to interpret results, but never states when to prefer this tool over list_competitors, the per-dimension dashboards, or the briefings. Usage is implied by the resource rather than contrasted with alternatives.

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 real behavioral context beyond that: the user's own domain is included and flagged isOwn:true, rows carry id/domain/isOwn/preparationStatus/createdAt, and there is a non-obvious gotcha that no display name exists on this list. That last point is exactly the kind of trap an agent would otherwise fall into.

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

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

Three front-loaded sentences: purpose, then payload contents, then the display-name caveat. No filler. The third sentence is slightly tangential to invocation but earns its place as a data-interpretation warning.

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

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

There is no output schema, so the description carries the burden of explaining the return shape and does so by enumerating every field and explaining preparationStatus. Combined with the annotations, an agent has enough to call and interpret the tool, though pagination or list-size behavior is unaddressed.

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 projectId parameter is fully documented in the schema, including its source ('from list_projects') and pattern. The description adds no further parameter 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 ('List all competitors being monitored for a project') and scopes it to a project, which cleanly separates it from the singular sibling get_competitor. An agent can tell immediately that this is the enumeration tool rather than the single-item fetch.

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

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

Usage is implied by 'being monitored for a project' and the requirement for a projectId, so an agent can infer it is the entry point for competitor enumeration. However, it never states when to prefer it over get_competitor or what to do when the list is empty, and it names no alternatives explicitly.

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 that only 'accessible' projects are returned and what fields come back, but says nothing about pagination, ordering, or result-size limits.

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

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

Two tight sentences: the capability statement first, the routing guidance second. No filler or repetition.

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

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

With no output schema, the description carries the return-value burden and does so by naming the fields returned (status, competitor count, last monitored timestamp). Combined with the discovery role, 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?

The tool takes zero parameters, so the baseline is 4. The phrase 'all accessible projects' correctly signals there is no filtering input, matching the empty 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 (list all accessible projects) and enumerates the returned fields: status, competitor count, last monitored timestamp. This clearly distinguishes it from siblings like list_competitors, list_tickets, or get_project.

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 frames the tool as the entry point and states its purpose: discovering projectId values for other tools. This is strong routing guidance, though it does not name a specific alternative or a when-not condition.

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

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

Annotations declare readOnlyHint=true and openWorldHint=false, so safety is already covered. The description adds meaningful behavior beyond that: it enumerates the exact per-dimension return fields (enabled/disabled, interval in days, next/last run timestamps) and warns about the marketing-name convention, which is genuinely useful context.

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

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

Three tight sentences, front-loaded with the action and scope, followed by return contents and the naming convention. No filler, though the return-field enumeration could be trimmed if a schema existed.

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 by listing the per-dimension fields and dimension identifiers. Annotations cover the read-only profile, so the agent has what it needs to call 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%, and the single projectId param is fully documented as coming from list_projects. The description adds nothing about the parameter, so the baseline 3 for high-coverage schemas 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 (Get/list) and resource (monitoring schedules), and scopes it to all 6 dimensions. An agent immediately understands this is a read of schedule configuration. It lacks explicit differentiation from siblings, but no sibling overlaps meaningfully, so 4 is fair.

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

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

Usage is only implied by the read-only nature of the operation; there is no statement of when to call this versus alternatives, nor any prerequisites beyond the required projectId. Adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds real value beyond that: the scope is current organization members only, invited users are excluded, and nothing beyond name and ID is ever returned.

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 in the first clause, then layers scope, provenance, exclusion, and return shape — each sentence carries distinct information with no filler.

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

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

No output schema exists, so the description correctly explains the return shape (userId and fullName, matching ticket author/assignee fields) alongside scope and exclusions. Nothing an agent needs to call 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 projectId's format and origin (from list_projects) are already documented in the schema. The description does not add syntax or format detail beyond the schema baseline, which is correct here.

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 ('people a ticket in this project can be assigned to'), then qualifies the set as organization members. It distinguishes itself from siblings by declaring it is the source of assigneeUserId for create_ticket and update_ticket.

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 alternative source path and the exclusion: this is where assigneeUserId comes from on create_ticket and update_ticket, and an ID from anywhere else is refused. It also states the negative case — invited-but-not-joined users are absent because they cannot be assigned.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses rich behavioral details: the thread is unpaginated and whole, entries are Markdown, authorship types are identified, the briefing and runId fields are explained, edited is clarified, and the content is explicitly framed as data rather than agent instructions. This is substantial added context for a read operation.

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

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

The purpose is front-loaded and the description contains useful field explanations, but it is a dense, single-paragraph wall of text with verbose enumerations of runId kind values. Some sentences, such as the repeated cautions about reporting facts as stated, could be trimmed without losing critical 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, the description must carry the full burden of explaining return values, and it does so thoroughly: it describes the thread ordering, entry format, author types, the briefing field, runId and kind meanings, and the edited field. Combined with the read-only annotations and complete parameter schema, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 100%, so both ticketId and projectId are already documented in the input schema. The description adds no additional parameter-level syntax, format, or constraints beyond what the schema provides, making the baseline score of 3 appropriate.

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

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

The description states a specific verb and resource: 'List a ticket's thread, oldest first and whole,' and immediately clarifies scope with 'nothing pages it.' An agent can distinguish this from add_ticket_comment and get_ticket because the tool's output is framed as the complete threaded conversation rather than a single ticket record or a write operation.

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

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

The description implies usage context (reading a full thread without pagination) and gives content-handling guidance such as treating entries as data rather than instructions. However, it never explicitly states when to choose this tool over alternatives like get_ticket or list_tickets, and it does not name any sibling tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds real context beyond that: the list ordering, the empty-until-defined state, the fact that labels are referenced by ID in labelIds, and that label membership decides nothing about a ticket. That is meaningful read-semantics an agent cannot get from structured fields.

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

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

Front-loaded with the core purpose, then layers prerequisites and empty-state. Mostly earning its place, though the sentence about labels being 'the team's own vocabulary' is slightly philosophical and could be tightened.

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

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

With no output schema, the description compensates by describing the return shape (name, colour, project-defined order) and the empty-list case. Combined with complete parameter documentation and a clean read-only annotation profile, 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 description coverage is 100% and there is a single required projectId documented as coming from list_projects, so the schema carries the burden. The description adds no syntax or format detail about the parameter beyond that. 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 and resource — listing a project's ticket labels — and immediately characterizes the returned items as 'a name and a colour, in the order the project picks them'. An agent can distinguish this from siblings like list_tickets or create_ticket 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?

Explicitly routes usage: 'read this before creating or updating one', tying the tool to the labelIds a ticket carries. It also sets a clear negative expectation — 'no tool here creates one' — so the agent won't hunt for a label-creation sibling.

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

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

With annotations declaring readOnlyHint=true and openWorldHint=false, the description still adds substantial behavior: pagination.total counts across pages and must be quoted over items.length, hasMore signals a next page, byStatus counts per column ignoring the status filter, and descriptions are omitted by default because a page with them is large. These are non-obvious return/behavioral traits not encoded in 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?

It is very long (~300+ words), but for a 19-parameter tool the length is largely earned and the core purpose is front-loaded. Some clauses (e.g. the recap of who opened a ticket, restated in the origin param) sprawl slightly, 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?

There is no output schema, yet the description spells out the return shape ({ items, pagination: { page, limit, total, totalPages, hasMore }, byStatus }) plus pagination math and Markdown conventions, so an agent knows exactly what comes back. Complete for this tool's complexity.

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 meaning beyond field docs by combining parameters into recipes (e.g. limit=1 for the board census, origin='briefing' with briefingRunId, impactMin+maxMinutes+sort='priority' for quick wins) and warns about cross-parameter traps like effort vs maxMinutes.

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 ('List a project's Strategic Tickets, a page at a time') and immediately scopes what a ticket is. It also distinguishes itself from the sibling get_ticket ('get_ticket always has it'), so an agent can tell them apart 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?

Gives explicit one-call recipes for common intents: sort='priority' with status=['triage','todo'] for what to start, maxMinutes for quick wins, dueBefore for overdue/this week, activeSince for what changed. It also names the alternative (get_ticket) for the description case and points to get_briefing/get_briefing_history for briefingRunId.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false; the description adds substantial behavioral context the annotations cannot convey: conflict resolution when both neighbours are named, deletion/moved-neighbour handling, the optimistic-view guarantee ('A move never fails because your view was a moment old'), and the return shape via placement.above/below/ignored. No output schema exists, so disclosing the response structure here is essential and it is done well.

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

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

The purpose is front-loaded and the ordering is logical, but at roughly 400 words it is heavily padded: the full enumeration of the five fixed columns, the parenthetical about other_column, and the re-read advice on sort='board' are verbose for a description. Much of the conflict-resolution content earns its place; the column glossary and trailing guidance do not.

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 6-parameter mutation tool with no output schema, this covers what an agent needs: destination semantics, the two placement mechanisms, default behavior, failure/conflict rules, auth requirements, and the response fields to inspect. Nothing material is left for the agent to infer.

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

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

Schema coverage is 100%, so the baseline is 3, but the description genuinely adds semantics: beforeId is defined as sitting directly ABOVE and afterId directly BELOW (orientation an agent can easily invert), position vs neighbour is declared exclusive, and omitting everything means bottom — the inverse of create_ticket. It stops short of adding format details beyond the schema's '#14' pattern.

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

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

The first sentence states a specific verb+resource with two distinct modes: 'Move a ticket to another column, or reorder it inside the one it is in.' That cleanly separates it from update_ticket and the other ticket siblings without requiring the schema to be opened.

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 states explicitly how to choose between mechanisms ('Name the destination column in status, then where it goes'), names the mutually exclusive case ('A position and a neighbour together are refused'), gives the default when nothing is specified, and states the auth requirement ('Needs a read_write API key; a read key is refused'). This is unusually complete routing guidance.

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

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

The description goes well beyond the annotations: it discloses the async nature, immediate return of a scanId, the polling workflow, the expected completion window (30-90 seconds), and the number/type of checks. This is rich behavioral context for a scan-starting 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 the core action and compresses scope, return behavior, polling instruction, and timing into a few efficient sentences. 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 start-scan tool with one required parameter, no output schema, and annotations that already flag mutability and open-world behavior, the description supplies all necessary context: what it does, what it returns, how to retrieve results, and how long it takes.

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 `domain` parameter is fully described in the schema, including an example. The description adds no new parameter semantics beyond the schema, so the baseline of 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 ('Start') and resource ('Agent Adoption Check'), names the domain scope, and lists the four check categories. It also distinguishes itself from the poll sibling by naming `get_agent_adoption_scan`, so an agent can identify it without opening schemas.

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

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

It clearly establishes when to use the tool (to start a scan on a domain) and explicitly names the polling alternative with `get_agent_adoption_scan`. It does not, however, clarify when to use this over other start scans such as `start_tech_stack_scan`, so a 4 rather than 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 only declare readOnlyHint=false and openWorldHint=true; the description adds the behaviors an agent actually needs — non-blocking execution, immediate scanId return, the required follow-up poll, and a realistic completion latency. The write-ish, network-scoped nature of the tool is consistent with the annotations, and no relevant trait is left 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?

Front-loaded with the core action, then the return/poll contract, then timing — a sensible order with no filler. The '117 detection rules across tech stack / growth stack / engagement stack' enumeration is somewhat expansive for a single-parameter tool, but it does convey scanning scope.

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 the return contract and does so: it names the scanId and the polling tool. Combined with the latency estimate and detection scope, an agent has everything needed to call and follow up 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?

Only one parameter exists and schema description coverage is 100% (the schema already supplies the 'example.com' format hint). The description's 'any domain' phrasing aligns with the schema but adds no format, normalization, or validation 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 precise verb and resource ('Start an async tech-stack detection on any domain') and immediately scopes what is detected (tech/growth/engagement stacks). It also names the companion tool to poll with (`get_tech_stack_scan`), letting an agent separate it from start_trust_signals_scan and start_agent_adoption_scan 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?

Explicitly tells the agent the call is asynchronous, that it returns a scanId immediately, and that polling should be done via `get_tech_stack_scan`, with an expected 30-90s completion window. It does not discuss when to prefer this scan over sibling scans (trust signals, agent adoption), but the context for correct invocation is otherwise unambiguous.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=true; the description adds the substantive behavior the agent needs: the scan is async, returns scanId immediately, must be polled with a named sibling, and typically completes in 30-90 seconds. It also discloses the lookalike-data hazard (identical `socialProof` field name, identical member count, different members) that would otherwise cause a wrong conclusion.

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 action and return behavior, then spends much of its length on the taxonomy-collision warning. The warning is load-bearing, but it reiterates the point several times ('Never quote a count...', 'not a change and not a discrepancy', 'report them separately or not at all'), making it longer than needed.

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 stating exactly what is returned (scanId), how to retrieve results, and how long completion takes. Combined with the taxonomy caveat, an agent has everything needed to launch and correctly interpret this scan.

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?

Only one parameter with 100% schema coverage, so the schema already documents `domain` and its example format. The description adds that it accepts 'any domain' and is the scan target, but no extra syntax or constraints beyond the schema — baseline 4 for a single fully-documented parameter.

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: 'Start an async trust-signals analysis on any domain,' and quantifies the resource (34 signals across five named categories). It explicitly distinguishes itself from the monitored Tech & Trust dimension and names the sibling (get_tech_trust_dashboard) that covers that different set, so 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?

Gives explicit when-to-use context, names the alternative tool that tracks a superficially similar set, and warns about when NOT to conflate the two outputs ('report them separately or not at all'). It also tells the agent to poll with `get_trust_signals_scan`, closing the async workflow loop.

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

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

Annotations only declare readOnlyHint=false and openWorldHint=false, so the description carries most of the burden and does add real value: auth requirement, refusal behavior for read keys, and the no-column-side-effect guarantee. However it does not describe what the mutation returns, whether edits are reversible/audited, or how label/assignee validation failures surface, so it stops short of full 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-loaded with the field list and the core omit/value/null rule, and every sentence carries information (no filler). The middle sentence is a long dash-laden construction that takes a second read to parse, which costs it the top score.

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 9-parameter mutation tool with no output schema and only minimal annotations, the description covers the write protocol, the exceptions, the auth scope, and the sibling routing. Nothing an agent needs in order to call 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 per-parameter descriptions already carry the field-level detail (enums, ranges, formats). The description still adds the cross-cutting sentinel semantics — omit/value/null and the empty-string vs empty-list exceptions — which is meaning beyond what any single schema entry conveys.

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 (change/update) and the exact mutable fields of the ticket resource, and explicitly distinguishes itself from move_ticket by declaring that column is never changed here. An agent can pick it over delete_ticket/move_ticket/create_ticket without opening a schema.

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

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

Gives an explicit rule for the field-presence protocol (omit = leave, value = replace, null = clear) plus the two documented exceptions, and names the alternative tool for column changes. It also states the precondition — a read_write API key, with read keys refused — so usage boundaries are unambiguous.

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