Trakkr

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

Annotations declare the mutation profile (readOnlyHint=false, openWorldHint=true, idempotentHint=false), and the description adds substantial non-obvious behavior: processing is async, the call returns fast with status='pending', chunking/embedding happens in the background, and duplicate content is rejected. These async and dedup traits are not derivable from 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-loads purpose, then the two modes, then processing behavior, then arg details, which is a logical order. It is somewhat long and the Args block partially restates the mode requirements already given in prose (content/url requiredness), a minor redundancy that keeps it just short of maximal conciseness.

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-param mutation tool with no output schema, the description covers mode selection, required inputs, async lifecycle, the polling path via get_knowledge, and failure conditions. An agent has everything needed to call it correctly and to handle the pending→ready/error transition.

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 only 17%, so the description carries the burden and does so well: it documents brand_id, source_type, content (with a ~50–100,000 token range and a ~200-character minimum), url (http/https, server-side fetch/extract), and name (default derivation). The only undocumented param, user_intent, has its own schema description, so nothing important is left ambiguous.

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 a source to the brand's knowledge base') and immediately frames the domain ('knowledge is the brand-truth Trakkr feeds into AI-facing content generation'). This clearly distinguishes it from get_knowledge (read) and manage_knowledge (sibling mutation), so an agent can tell what it does 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 enumerates the two modes (source_type='text' vs 'url') with the conditions and required fields for each, and states the dupe-rejection rule. It also routes the agent to the follow-up sibling: poll get_knowledge(brand_id, view='sources'). When-to-use 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 already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the safety profile is covered. The description adds useful routing context (which actions consume prompts vs prompt_ids) but does not disclose that bulk_delete is irreversible, whether existing tracking data is affected, or any auth/permission requirements. With annotations carrying the safety burden, a 3 is appropriate.

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 a one-line purpose, followed by action routing and then an Args block – a logical, scannable order. There is mild redundancy between the prose action guidance and the Args list, but nothing egregious.

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 destructive mutation tool with no output schema and five params, the description covers the operations and most input formats adequately, and the destructive annotation covers safety. The gaps are the unmentioned user_intent param and the absence of any note on irreversibility of deletion or return 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?

Schema description coverage is only 20%, so the description must compensate, and it largely does: it documents action enum values, brand_id as required, the prompts object shape ({text, active?, focus_area?, intent?, audience?}), and the prompt_ids format. It nonetheless omits the user_intent parameter entirely, leaving one of five params undocumented in both schema and description.

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 ('Manage prompts in bulk — create, delete, activate, or deactivate many at once') and enumerates the four supported operations. This clearly distinguishes it from the singular sibling manage_prompt and the read-only list_prompts.

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 to the correct action for each task ('Use action=bulk_create to add multiple prompts', 'action=bulk_delete to remove multiple prompts by ID'), which is strong intra-tool guidance. However, it never states when to prefer this tool over sibling manage_prompt (single) or suggest_prompts, so sibling selection 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?

Beyond the annotations, it discloses real behavioral traits: committing 'freezes how it will be measured' (enabling before/after), dismissing records a reason 'so the pool learns,' and snoozing is temporary. It also states a crucial permission boundary — the tool 'cannot grant an agent permission to do anything; autonomy is set per brand in the product, never over the API' — which the destructiveHint=true annotation merely implies. The description is consistent with the annotations.

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

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

The purpose and the three modes are front-loaded, followed by rationale and an explicit Args list mapping each parameter to its meaning. It is somewhat verbose relative to a 3-way enum decision, but each sentence adds behavioral or parameter value 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?

For a 6-parameter mutation tool with no output schema and low schema coverage, the description is largely sufficient: it covers the decision semantics, the consequence of each action, permissions, and five of six parameters. Return value format is not explained, but with no output schema that is less critical.

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 only 17%, so the description must carry the load, and it does for most parameters: it defines the action enum semantics, notes commit is the default, marks reason as recommended when action='dismiss', and gives snooze_days a default of 7. It omits user_intent, though the schema itself documents that field, so the gap is minor.

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: 'Decide on one suggestion: commit it, dismiss it, or snooze it,' and immediately enumerates the three decision modes. It also names list_opportunity_pool as the origin of the opportunity_id, letting an agent distinguish this tool from retrieval siblings like get_opportunities and list_opportunity_pool.

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 explains when to use each action branch (committing creates tracked work, dismissing takes a reason, snoozing hides and returns) and cites list_opportunity_pool as the prerequisite source. It does not explicitly contrast itself with nearby mutating siblings like manage_action or manage_reddit_opportunity, so there is a small gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, so the safety profile is covered. The description adds useful output-shape context (per-brand row of metrics over a shared window), which exceeds the annotations. However, it does not state permission requirements, behavior on invalid brand IDs, or metric availability limits, so it adds only moderate value.

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 one-line purpose and workflow framing, then uses a clean Args block. It is appropriately sized, though the workflow sentences could be slightly tighter without losing meaning.

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 comparison tool with annotations covering safety and no output schema, the description provides purpose, workflow context, and full param constraints. It is nearly complete; only explicit sibling differentiation (e.g., vs compare_reports) and edge-case behavior are 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 only 25% (only user_intent is documented in-schema). The description compensates by documenting brand_ids (2-10 required), days (7-365, default 30), and the metrics enum values ('visibility', 'citations', 'actions', default all). It leaves user_intent undocumented, but the schema already covers that parameter's description, so the gap is minor.

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 ('Compare multiple brands side by side') and adds a concrete workflow framing (agency/pitch, prospect vs competitors, two client brands). This distinguishes it from generic report tools, though it does not explicitly name the nearest sibling, compare_reports, or explain how it differs.

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 agency/pitch framing implies when to use it (competitive comparison), but there is no explicit when-not-to-use guidance and no reference to alternatives such as compare_reports or get_competitors. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds the semantic that this is a differential analysis across two windows, but says nothing about output shape, pagination, or period-boundary semantics. With annotations carrying the safety burden, a 3 is appropriate.

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 two prose sentences are tight and front-loaded with the core action and value. The Args block repeats information largely already present in the schema titles, which is slightly redundant but aids readability for a 5-required-param tool. No padding beyond that.

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?

Covers required params with formats, states the read-only comparison intent, and there is no output schema so return values need not be described. Missing only edge-case semantics (overlapping periods, ordering of start/end values) and the unmentioned user_intent hint, which is 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 description coverage is 17%, so the schema documents only user_intent explicitly; the description documents the five required params with date formats (YYYY-MM-DD). That compensates for most of the coverage gap, but the description omits user_intent entirely and gives no constraints such as baseline_end <= comparison_start. Baseline 3 reflects partial compensation.

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 ('compare visibility between two time periods') and elaborates what the comparison contains (how AI visibility changed between baseline and comparison periods). A sibling like compare_brands exists, but the description's 'two time periods' framing distinguishes this tool from that brand-vs-brand comparison well enough.

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?

Offers a use-case hint ('useful for measuring the impact of content changes or campaigns') which implies when to reach for it, but does not name alternatives like get_period_summary or compare_brands, nor any when-not-to-use condition. Usage is implied rather than directed.

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 annotations, the description discloses caching and quota behavior, that the brand's own site is always excluded, that it does not measure indexing or forecast citations, and that page excerpts are untrusted text. This gives the agent a clear model of side effects, limitations, and safe handling of returned content.

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

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

The description is dense but every section earns its place: a one-sentence summary, behavioral caveats, quota rules, security warning, and parameter explanations. It is front-loaded with the core purpose and structured so agents can quickly extract invocation requirements.

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?

Even though there is no output schema, the description details what is returned: up to five candidates, page titles, excerpts, contact pages, citation_status, and page_kind. Combined with access requirements, quota limits, caching semantics, and security warnings, an agent has everything needed to invoke this correctly.

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

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

Schema description coverage is only 13%, but the Args block substantially compensates by explaining brand_id, topic, prompt_ids, seed_domain, market, language, and new_only. It misses user_intent, though that parameter has its own schema description, so the gap is minor.

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: 'Find independent publishers worth pitching or partnering with for a topic.' It differentiates itself from siblings by explicitly naming get_opportunities as the alternative for publishers that already cite rivals but not the brand.

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

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

The description gives explicit when-to-use guidance: 'Only call when the user asks to find publishers' and notes the editor-access requirement. It also provides a concrete fallback strategy for busy categories and names get_opportunities as the alternative, 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds bulk-scope and the lookback/limit defaults, but says nothing about the output artifact itself (file, URL, or inline payload), which matters for an export tool. Above the annotation baseline but not rich.

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

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

Front-loaded purpose sentence followed by a short context line and a compact Args block that maps one-to-one onto the parameters. Efficient overall; the second line is mildly redundant with the first but still adds the 'bulk/external' framing.

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 bulk export with no output schema, the definition covers inputs well but never describes what comes back — inline JSON/CSV, a download reference, or row-count behavior for the 1000/10000 limits. That is a real gap for an agent deciding how to report results.

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 only 17%, so the description must carry the load, and it documents 5 of 6 parameters with defaults and ranges (brand_id, data_type, format, days 1-365, limit 1-10000). It omits user_intent, the one parameter that actually carries a schema-level description, so the coverage gap is minor rather than serious.

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 ('Export visibility data as JSON or CSV', 'Bulk export of Trakkr data') and frames it as bulk external reporting, which separates it from the many get_* / list_* siblings. It does not name a sibling directly, so it stops short of 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?

"for external analysis or reporting" implies when this is appropriate, and the 'Bulk' qualifier hints at the difference from per-item readers. However, there is no explicit statement of when NOT to use it (e.g., use get_results for a single query) or any prerequisites, so usage remains implied rather than stated.

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

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

Adds substantial context beyond annotations: async/queued behavior, ~1-3 minute background write time, credit consumption with a specific failure message when credits are exhausted, and an explicit 'no auto-publish path' guarantee. Annotations only cover readOnly/idempotent hints; the description carries the operational reality.

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

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

Front-loaded with the one-line purpose, then async/cost details, then the polling workflow, then the no-publish guarantee, then args. Every paragraph earns its place with zero 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?

Given 6 params, no output schema, and an async tool, the description covers the lifecycle (queue → background → poll → read fields), cost model, error condition, and publish boundary. Nothing an agent needs in order to call and follow up 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 only 17%, so the description must compensate. It does for most: primary_prompt with an example and 3-500 char constraint, secondary_prompts as 'extra angles', word_target 300-6000 with default, template_id purpose. brand_id is only labeled 'required' with no extra semantics, and user_intent (an analytics hint) is never mentioned in the description despite being in the schema.

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

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

States a specific verb + resource ('Generate a brand article') and immediately distinguishes itself from get_articles (reads) and generate_report (sibling asset type). An agent knows this is the write/generation entry point for articles.

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 workflow: call this, then poll get_articles(brand_id, view='detail', article_id=<id>) until status is 'draft' or 'error', then read content and llm_score. Names the exact follow-up tool and terminal states, so no inference is needed.

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 establish the mutation profile (readOnlyHint=false, destructiveHint=false), and the description adds that generation is asynchronous and takes 1-2 minutes, which is valuable behavioral context beyond the structured fields. It doesn't note that idempotentHint=false means repeated calls may create duplicate reports, a minor gap.

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

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

Front-loaded with purpose, then latency, then next step, then args in a scannable layout. The opening two sentences overlap ('Generate an AI visibility report' / 'Creates a comprehensive report...'), 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?

For an async generation tool with no output schema, the description covers purpose, latency expectation, and the retrieval path via get_reports, which is what an agent needs to call and follow up correctly. Details like duplicate-call behavior are the only meaningful omission.

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 only 25%, so the description must carry parameter meaning, and it does: it documents brand_id as required, interprets report_type values ('executive' (summary), 'weekly', 'full'), and lists time_range options with defaults. It omits the schema-documented user_intent param, but overall compensates well for the low coverage.

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

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

States a specific verb (generate) and resource (AI visibility report) and adds scope ('analyzing the brand's AI search visibility'). The name and description clearly separate it from retrieval siblings like get_reports and compare_reports, though the first two sentences restate the purpose somewhat.

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 get_reports as the follow-up for checking status and retrieving the finished report, which is actionable guidance. However, it gives no 'when-not-to-use' exclusions and doesn't explain how to choose between report_type variants at the usage 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 cover safety (readOnly, idempotent, non-destructive) so the bar is lower, yet the description adds substantial behavior: the exact return shape including nested action_data, family, page scope, and the fact that result is null until the measurement window closes. This is exactly the context an agent needs to interpret and continue after the call.

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 canonical-surface claim, then structured into recipes and an Args list. It is long, but the length is earned by the 14-param surface and the enumeration of return fields; the return-field sentence is dense but useful.

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

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

No output schema exists, so the description must describe returns, and it does thoroughly (field list, null-result timing, deep_link, evidence shape). Combined with the recipes and full parameter coverage, an agent has everything needed to call and interpret it.

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

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

With only 7% schema description coverage, the description carries nearly the full burden and mostly succeeds: it explains status semantics (open = pending+in_progress+snoozed), all category/source/action_type values, lens, quick_win, search scope, and sort options with defaults. The only gap is user_intent, which appears in the schema but is not addressed in the description.

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 recommended actions for a brand') and positions it as the canonical 'what should the brand do' surface that unifies all Trakkr signals. This clearly distinguishes it from siblings like get_action_stats, get_results, and manage_action.

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 when to use it (canonical queue surface) and provides four concrete recipes showing filter combinations for distinct workflows. It also names get_results as the alternative for measured results, and all signals that feed the queue.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered structurally. The description adds that this is an aggregate snapshot with a fixed set of derived metrics, but discloses no auth, rate-limit, or freshness/caching caveats. Adequate against a low bar but not rich.

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 the returned metrics, then an Args block. Every sentence carries information, though the multi-line metric list is slightly padded by formatting rather than prose.

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

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

With no output schema, the description usefully enumerates the return fields, which is the key context an agent needs. The remaining gap is the undocumented user_intent parameter, which the description never addresses.

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 50%: brand_id has no schema description and is only restated as 'The brand (required)', and the user_intent analytics hint parameter is not mentioned at all in the description. It partially compensates for the brand_id gap but leaves the second parameter entirely to the schema.

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

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

States a specific verb+resource ('Aggregate counts for the brand's action queue') and enumerates the exact metrics returned (status totals, quick-win count, completion rate, category/action_type/source breakdowns). An agent can distinguish this from the sibling get_actions because the description frames it as the summary view.

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 positions usage: 'a one-shot "how does the queue look right now" call before paging through it,' which contrasts with the paged detail tool. No explicit exclusions or named alternative, but the when-to-use 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/idempotent/non-destructive safely, so the bar is lower. The description adds real value beyond that: it explains the two view modes, that 'detail' requires article_id, and that it returns full body content. It doesn't discuss rate limits or pagination behavior, but for a read tool with annotations this is solid.

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, then view modes, then a structured args list. It's a bit long but every line earns its place given the low schema coverage. No wasted prose.

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 an 8-param read tool with low schema coverage and no output schema, the description covers the essential params and the two operation modes. The main missing piece is the status enum values and the user_intent param, but overall it gives an agent enough to call the tool correctly.

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

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

Schema coverage is very low (13%), so the description must compensate, and it largely does: it explains brand_id, view values with meanings, article_id requirement, status filter, standalone_only's effect, and limit/offset defaults and range. It omits user_intent and doesn't define status enum values (which the schema does via enum), leaving a small gap.

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 (Read) and resource (brand articles authored inside Trakkr), and adds the distinguishing trait that these are long-form pieces from the in-app editor with AI-visibility scoring. It doesn't explicitly name or differentiate from siblings like get_content_ideas or generate_article, but the resource is specific enough to disambiguate.

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 use context: 'surface what's been published and pull body content for review or syndication', and the view modes are explained with their conditions. It doesn't state when NOT to use it or name an alternative tool, 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 already declare readOnly/ idempotent/ non-destructive, and the description goes well beyond them: dismissal semantics keyed on brand+check+URL, persistence across re-scans, partial-dismissal staying open, and the no_audit_yet return signal. This is rich behavioral disclosure the 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?

Front-loads what it returns and the one-call value proposition, then the dismissal nuance, then a clean Args list. The dismissal paragraph is dense but each sentence adds non-obvious semantics; size is justified for a 13-parameter tool, though it is longer than strictly necessary.

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 still specifies what comes back (issue list, worst-scoring pages, site-wide rollups like has_llms_txt and ai_crawler_blocked) plus the status='no_audit_yet' edge case. With every filter documented, an agent can call this correctly without further information.

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 only 8%, so the description must carry the burden, and it does: every filter is explained with format, accepted values, defaults, and valid ranges (severity enum values, issues_limit 1-50, pages_limit 1-100 with rationale, check_name substring examples). Only user_intent is left undocumented.

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 audit issues + flagged pages for an AI-search technical audit') and scopes it to exactly what the Optimize Findings/Pages tabs render, which distinguishes it from siblings like list_audits or get_page_analysis.

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 context for when to use it ('answer is this site set up for AI search? in one call') plus a key constraint (read-only, never triggers an audit) and the no_audit_yet case. It does not explicitly name a sibling alternative or state when not to use it, so it stops short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description confirms this ('read-only pull, safe to call freely') while adding genuinely new behavioral context: the cursor round-trip pattern, and the latency cadence (crawler near real-time vs daily research-run detection). The cadence disclosure is information no annotation or schema provides.

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 cadence, then an Args block. The Args list partially restates schema fields, but with 20% schema coverage that restatement is justified rather than redundant. Slightly verbose in the middle paragraph but every sentence conveys usable information.

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

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

With no output schema, the description appropriately enumerates what the digest returns rather than leaving return shape unknown, and it covers cursor semantics, cadence, and defaults. The only gap is the undocumented user_intent parameter and the lack of explicit divergence from the get_notifications sibling.

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 only 20%, so the description carries the burden and does so well: it documents brand_id (required), since (ISO-8601, latest_seen semantics, omission behavior), days (1-180, default 7), and limit (1-200, default 50) with interaction logic ('days used only when since is absent'). It omits the fifth parameter user_intent, which is documented in the schema, so it's not fully complete.

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?

Front-loaded clause 'What changed for a brand since you last looked' gives a specific verb and resource, and the body enumerates exactly what the feed contains (visibility shifts, citations, competitor moves, rank changes, crawler signals, opportunities, reports). An agent can distinguish this activity-feed digest from siblings like get_latest_research or get_rankings.

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 describes the intended workflow: pair with the trakkr-watch prompt, capture latest_seen, and pass it back as `since` for incremental reads. It stops short of naming when NOT to use it (e.g. versus get_notifications or get_latest_research, which the 'same notifications' phrasing could overlap with), so it's strong but not fully differentiating.

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 readOnly/idempotent/non-destructive safety profile. The description adds genuinely useful behavioral context beyond that: response_format's context-protection behavior, the period-freezing semantics, and the days_back caveat. However, it doesn't disclose return shape details or rate/cost characteristics; with annotations covering safety, a 3 reflects solid but incomplete added value.

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 opening is well front-loaded, but the bulleted view list and Args section are long and partially redundant with the schema (e.g., restating defaults for days, limit). Information density is high, but for a 12-param tool it borders on verbose rather than trimmed.

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

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

Given 12 parameters, one output-less schema, and read-only annotations, the description is nearly complete: it explains views, filters, pagination, and the response_format trade-off. It could still note expected return fields per view, but the essentials for correct invocation are 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 only 25%, so the description must compensate — and it does. It explains view, days, period, limit, offset, domain, days_back, tag_ids, prompt_text, and response_format semantics that the schema alone does not, including interactions (days ignored when period set; days_back capped at 30).

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 citation data showing which URLs AI models cite') and distinguishes itself from every sibling by domain scope. The opening sentence makes it clear this returns citation sources, not rankings, traffic, or prominence scores.

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 enumerates all 11 views with a one-line description of what each returns and the constraints each imposes (e.g., view='sources' requires 'domain', period only works with top_pages/analytics, feed uses days_back). This is effectively a complete when-to-use map.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description still adds real behavioral context: that 'over_time' is recomputed from stored daily results and available for the whole window immediately, that 'period' overrides 'days' and changes the response shape (with the specific period block fields named), and that 'concise' trims matrices to protect context while 'detailed' returns the full grid.

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, then cleanly sectioned into Views and Args. It is longer than average, and a few clauses (the business-line quote example, the Competitive Trend chart aside) are illustrative rather than load-bearing, but almost every line carries decision-relevant information.

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

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

For a 9-parameter, no-output-schema tool, the description is complete enough to call correctly: it covers views, per-parameter constraints, the period-block response shape, and the concise/detailed tradeoff. An agent would not need to guess at response structure for the main paths.

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 only 11%, so the description carries the burden and does so thoroughly: it explains brand_id, every enum value of view, competitor behavior on both 'head-to-head' and 'over_time' (including that it pulls in competitors outside the top slice), days vs. period interaction, tag_ids semantics plus its dependency on list_tags, and limit's range and ordering. This is meaning well beyond what the bare schema enums convey.

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 competitor analysis data from AI search') and then enumerates seven named views, each with a one-line definition of the data it returns. An agent knows exactly what this produces without opening the schema, and the view list distinguishes it from single-metric siblings like get_visibility_scores or get_rankings.

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 view descriptions function as usage guidance, and constraints are explicit: 'head-to-head' requires the competitor param, 'period' is view='summary' only, 'limit' is 'over_time' only. What's missing is routing against siblings — compare_brands and compare_reports are never mentioned as alternatives for cross-brand comparisons, so the agent must infer when this tool is the right one.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds useful return-shape context (topic, rationale, priority score) but says nothing about auth needs, rate limits, or why ideas might be empty. That is adequate-but-shallow against an annotation-backed baseline.

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

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

Front-loaded with purpose and return format before the Args block, with no wasted prose. It does restate schema facts (limit range, default, status enum) that the agent could already read, costing a little density.

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, no-output-schema tool, the description supplies the return contract (topic, rationale, priority score) that the schema does not. The main gap is the undocumented user_intent parameter and the absence of any filtering/pagination behavior notes.

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 only 20%, so the description must carry the load — and it does document 4 of 5 parameters with meaning (brand to check, results per page 1-200 default 50, pagination offset, status as a filter with its enum values). It omits the user_intent analytics hint entirely, which is the sole parameter the schema itself documents, so coverage is incomplete.

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

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

The description names a specific verb+resource ('Get AI-generated content ideas') and explains the mechanism ('based on citation gap analysis'), so the agent knows what it produces. It does not, however, distinguish this from sibling list-style tools like get_opportunities, get_actions, or suggest_prompts, which prevents a top score.

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?

There is no explicit when-to-use guidance, no prerequisites, and no routing to or away from alternatives. The agent must infer from the purpose alone that this is the tool for generating new content suggestions versus reading existing articles or opportunities.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds useful content context (what data comes back), but says nothing about date-range behavior, the range_preset/start_date/end_date interaction, pagination, or rate 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 short sentences, purpose front-loaded, then a compact enumeration of returned artifacts. No filler or redundancy; could be slightly tighter but is well structured for 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?

With no output schema, the description does useful work listing the five returned data shapes. However, for a 5-parameter tool at 20% schema coverage it leaves the date-range and preset semantics entirely unexplained, which is a real gap for correct invocation.

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

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

Five parameters with only 20% schema description coverage — brand_id, start_date, end_date, and range_preset are undocumented in the schema, and the description explains none of them. The description's listed returns do not compensate for the parameter gap, so it fails to do the burden-carrying that low coverage requires.

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 ('Get the crawler Access tab data') plus an enumeration of returned artifacts (findings, bot access matrix, robots.txt, llms.txt, submit-to-search status) that meaningfully distinguishes it from crawler siblings like get_crawler_submit_status or get_crawler_overview. It does not, however, name any alternative tool, so differentiation is implicit rather than explicit.

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

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

There is no when-to-use or when-not-to-use guidance, no prerequisites, and no routing to alternatives despite five crawler-related siblings (get_crawler_detail, get_crawler_live, get_crawler_overview, get_crawler_pages, get_crawler_submit_status). The 'Access tab' framing implies a dashboard context but never states it as a selection rule.

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

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

Annotations already declare readOnly, idempotent, non-destructive. Description adds drawer-section return content and the fact that intent/platform/search/status are ignored for kind='page', which is useful filtering semantics. No auth, rate-limit, or failure-mode 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?

Front-loaded with what the tool returns, then kind routing, then args. Efficient and readable. Slight redundancy between the kind bullet list and the args section, but not wasteful.

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?

Covers purpose, return content, kind-to-entity mapping, and per-kind filter applicability for an 11-param tool with no output schema and low schema coverage. Could mention pagination/volume or failure behavior, but is otherwise complete.

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

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

Schema coverage is only 9%, so the description must compensate and it does: kind-to-entity_id mapping, range_preset defaults, custom date requirements and format, filter applicability per kind, and status/intent allowed values are all described. It meaningfully documents an otherwise undescribed 11-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?

Clear specific verb+resource: opens the crawler drawer data for one entity and enumerates the sections returned (verdict, pipeline, health, next step, traffic, diagnostics). Distinguishes the page/path/bot kinds. No explicit sibling comparison, but get_crawler_pages is referenced as the source of path/bot ids, which implicitly routes the agent.

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 each kind applies and which filters are ignored (path/bot only), and points to get_crawler_pages(lens='paths'/'bots') to obtain entity ids. No explicit when-not-to-use, but the kind routing is strong guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds the custom-range requirement and the per-view sort key constraints, but says nothing about auth needs, rate limits, or pagination semantics beyond the existence of a cursor.

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

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

Front-loaded purpose followed by a structured Views block and an Args block; every line maps to a real parameter or view. It is long, but with 14 parameters that length is mostly earned 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?

For a 14-parameter, low-schema-coverage, no-output-schema tool this is close to sufficient: filters, range logic, sorting, and pagination are all covered. It stops short of describing what each view's records actually contain, which the absent output schema would otherwise need.

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 only 7%, so the description carries the burden and does so well: it documents accepted range values, required-with-custom date semantics and format, comma-separated platform/http_status syntax, search behavior, and the valid sort_by values per view. Only the analytics-hint user_intent param is left to 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 the crawler Live tab data') and enumerates the three views with one-line meanings, so the agent knows exactly what this returns. It does not explicitly contrast itself with the many crawler siblings (get_crawler_detail, get_crawler_overview, get_crawler_pages), so a 5 is not warranted.

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 view list implies which mode to pick for which need, and the conditional requirement for start/end_date is spelled out. However, there is no explicit guidance on when to prefer this tool over get_crawler_detail, get_crawler_overview, or get_crawler_pages, nor any 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 already declare the tool read-only, idempotent, and non-destructive, so the description does not need to restate safety. The added behavioral context about sources in 'error' or 'no_data' being excluded from figures and connections.note providing remediation guidance is valuable 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?

The description is front-loaded with the tool's purpose and return contents, followed by an important caveat and a compact Args list. Every sentence earns its place, with no filler or repetition of schema details already visible in the input schema.

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

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

Without an output schema, the description provides a good inventory of the returned sections plus a nuanced data-quality caveat. It does not mention the user_intent parameter in the Args block, though the schema itself documents it, and it could describe more about the shape of time series or metrics, but overall it is sufficient for selecting and invoking the tool correctly.

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

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

Schema description coverage is only 17%, but the Args section compensates thoroughly: it documents brand_id as required, explains range_preset options with a default, defines start_date and end_date as required for custom ranges with YYYY-MM-DD format, and enumerates compare_to choices. This adds real meaning beyond the schema fields.

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

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

The description clearly states a specific verb and resource: it retrieves the crawler dashboard overview for a brand and enumerates what it includes (metrics, time series, platform breakdown, top pages, recent preview). It does not explicitly differentiate from sibling tools like get_crawler_detail or get_crawler_live, but the overview scope is evident from the content.

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

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

The description gives clear context about what the tool returns and even instructs the agent to mention missing sources to the user, but it never explicitly states when to choose this tool over alternatives like get_crawler_detail or get_crawler_pages. Usage is implied by the dashboard-overview framing rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds pagination behavior (cursor returned from a previous call, limit 1-100) and the conditional requirement that start/end_date are needed only with range_preset='custom', but says nothing about auth, rate limits, or result shape.

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

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

Front-loads the purpose, then a compact lens map, then a scannable arg list. Given 14 parameters it wastes no words; each line adds an actionable constraint or default.

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 only 1 required parameter, an agent has enough to build a valid call: filters, sorting, and pagination are all documented. Completeness is slightly undercut by the absent return-value description and the undocumented user_intent param, but neither blocks correct invocation.

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

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

Schema description coverage is only 7%, so the description carries almost the entire burden and largely delivers: it documents date formats, the conditional date requirement, intent values, search targets, status filter, and crucially the lens-dependent valid values for sort_by. The only parameter it omits is user_intent, which the schema itself describes.

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 crawler Pages tab data') and immediately enumerates the three lenses that define the view. It is clear what the tool returns, though it never explicitly distinguishes itself from close siblings such as get_crawler_detail or get_crawler_overview.

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 lens list and defaults (range_preset=30d, intent=all, status=all, sort_dir=desc) imply how to configure a call, and the sort_by/lens dependency is flagged. There is no explicit when-to-use or when-not-to-use guidance versus the other crawler tools, so usage must be 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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description contributes the notion of a 'summary' (an aggregated view) over submission statuses, but says nothing about pagination, result limits, or how the url/status/date filters behave. With annotations carrying the main load, a 3 is fair.

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?

A single front-loaded sentence with no filler or redundancy. It is efficient, though for a 7-parameter tool the brevity borders on under-specification rather than pure conciseness.

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 7 parameters, 14% schema coverage, and no output schema, the description leaves an agent unable to construct a correct call — the filtering semantics and date/preset interaction are undocumented. It is far too thin for the 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 only 14% across 7 parameters, so the description must compensate — and it does not. It never explains that 'urls' accepts one or more crawler URLs, what the pending/success/failed status filter means, how start_date/end_date interact with range_preset (default 30d), or the purpose of brand_id and user_intent.

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 (submit-to-search status and summary for crawler URLs), which is enough to distinguish it from the write-side sibling submit_crawler_to_search. It does not explicitly differentiate itself from the other crawler tools (get_crawler_overview, get_crawler_pages, etc.), so it stops 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?

No guidance on when to use this versus alternatives such as get_crawler_overview or submit_crawler_to_search, and no prerequisites or exclusions are stated. The pairing with submit_crawler_to_search is inferable only from the name, not from the description text.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered structurally. The description adds the meaning of each view mode, but says nothing about auth scope, pagination mechanics, or return content 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?

Front-loaded purpose sentence followed by three usage bullets and a compact Args list; each line maps to an action. The Args block partly restates the usage bullets, which is mild 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?

With no output schema, the description should ideally convey what a 'result' actually contains or how history entries are shaped; it only gestures at this ('past diagnoses', 'remaining quota'). Adequate for invocation, incomplete for interpreting the response.

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

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

Schema coverage is only 20%, so the description carries real weight and does document brand_id, diagnosis_id, view, and limit (with 1-100 range and default 20). It omits user_intent, but that param is self-documented in the schema; the only flaw is listing view as 'history' or 'usage' while the enum also allows 'result'.

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 results of a diagnosis') and immediately broadens to the two auxiliary views it serves. It is distinguishable from write-path siblings like run_diagnosis, though it doesn't name them 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?

Gives three concrete invocation patterns mapping parameter combinations to intent (diagnosis_id for one result, brand_id+view='history' for past runs, brand_id+view='usage' for quota). Clear context, but no explicit exclusions or prerequisites (e.g., that a diagnosis must exist first).

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, idempotentHint=true, openWorldHint=false, destructiveHint=false. The description reinforces the read-only nature by explaining the purpose of the data and the read/write boundary. It does not mention pagination or output shape, but with this rich annotation set the bar is lower and the added semantic context is meaningful.

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, then a definition, then view semantics, then args. The structure is excellent. Minor padding in the definition sentence, but every element is purposeful.

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

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

Given the rich annotations and the lack of an output schema, the description covers the essentials: what is read, the two modes of operation, and the read-only boundary. The one missing piece is a note on the user_intent parameter and return format, but for a read-only lookup tool this is close to complete.

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

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

Schema description coverage is 33% and the description compensates by explaining what the enum view values ('sources', 'stats') return. brand_id is described as required. The third parameter, user_intent, is not mentioned in the description, leaving a small gap, but overall the description substantially closes the schema coverage gap.

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 ('Read the brand's knowledge base sources') and defines what knowledge entries are. The sibling set includes add_knowledge and manage_knowledge, and the description explicitly draws the boundary with 'Read-only here; authoring stays in the editor,' so an agent can tell this apart from the write 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?

Explicitly names the two views and what each returns, and clearly excludes authoring ('authoring stays in the editor'), pointing the agent to add_knowledge/manage_knowledge for writes. The when-to-use and when-not-to-use conditions are both present.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it returns the full analytics payload, the shape matches get_research_run, and it only returns the newest completed run, which explains why a missing result is possible.

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 one-line purpose, then the canonical use case, then the args list in a scannable structure. Slightly more verbose than strictly necessary in the middle paragraph, but every line carries actionable information.

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

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

For a read-only tool with no output schema, the description adequately closes the loop by describing the return payload and its relationship to get_research_run. The only omission is any mention of user_intent, and pagination semantics for the results array are only lightly implied.

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 only 20%, so the description must compensate, and it largely does: brand_id is marked required, report_type's two enum values and the omit-for-either behavior are explained, and results_limit/results_offset get ranges and defaults that add context beyond the raw schema. It does not mention the user_intent parameter, leaving one gap.

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 most recent ready prompt research run for a brand') and explicitly frames itself as the canonical 'what does my latest research show' tool. It also names the sibling combination (get_research_runs + get_research_run) it replaces, so an agent can differentiate 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?

Gives an explicit selection rule: prefer this over get_research_runs + get_research_run when you only want the current state. That is a concrete when-to-use statement naming the alternatives, with no inference required.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds substantive behavior: when `period` is supplied, `days` is ignored, the response carries a `period` block, total_queries becomes measured days, visibility_rate becomes an average, and top_3 fields are null. That is meaningful disclosure about a mode switch 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?

Front-loads the purpose, then the platform scope, then a compact Args block. Every line carries information; the only minor drag is that the purpose sentence and the 'Useful for' sentence partly overlap.

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 correctly explains the return-shape difference in `period` mode. It does not describe the normal (non-period) per-model return fields, which is a modest gap for an analytics tool, but nothing needed to invoke it correctly is missing.

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

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

With schema coverage at only 20%, the description does the heavy lifting: it documents brand_id (required), days (7-365, default 30), period (YYYY-MM or YYYY-Qn format plus its override behavior), and include_trends. Only user_intent is left to the schema, and its schema text is self-explanatory, so the description nearly compensates for the coverage gap.

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 visibility breakdown by AI model') and clarifies the scope is per-platform (ChatGPT, Perplexity, Gemini, Claude, Copilot), which distinguishes it from the overall sibling get_visibility_scores. It does not explicitly name that sibling as the alternative, so it stops 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?

'Useful for understanding which AI models mention the brand most' implies a use case but never states when to pick this over get_visibility_scores, compare_brands, or compare_reports. No exclusions or preconditions are given, leaving the routing decision 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 readOnly/idempotent/no-destructive behavior, so the description earns credit for adding the Scale plan prerequisite and explaining the temporal evolution of narrative data. It still does not describe return shape or pagination, but the added plan requirement is meaningful behavioral 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?

The description is front-loaded with a short concept explanation followed by a compact Args list. It is efficient and readable, though the Args list partly repeats schema information rather than adding purely new detail.

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

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

For a read-only tool with no output schema and five parameters, the description explains the concept and most inputs but does not describe what data is returned or its shape. It also omits user_intent from the narrative text, leaving the output contract underspecified.

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 only 20% schema description coverage, the description does useful work: it documents brand_id as required, narrative_id as optional, include values ('snapshots', 'correctives'), and days as a 7-365 lookback with default 90. It omits user_intent from the text, but that parameter already has schema-level description.

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 ('Get narrative intelligence data') and clarifies the concept: tracking topics/storylines across AI models over time. It does not explicitly distinguish itself from siblings like get_perception or get_visibility_scores, so it misses full differentiation.

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 context for when narratives are useful and notes the Scale plan requirement, but it does not state when-not to use this tool or name alternative tools for overlapping needs. Usage is implied rather than directed.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety and idempotency profile is covered. The description adds the scoping constraint via the days lookback window, but does not disclose pagination behavior or rate limits. With annotations doing the heavy lifting, a 3 is appropriate.

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

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

Well-structured with clear sections for purpose, views, and args. It is front-loaded and every sentence adds value. Slightly verbose in the activity feed elaborations but acceptable.

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

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

Given annotations, schema, and no output schema, the description is mostly complete. It covers the tool's purpose, views, and key arguments. The omission of the user_intent parameter and lack of return format details are minor gaps, but for a read-only tool they are not critical.

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 only 14%, so the description must compensate. It does so for most parameters by listing them with constraints (e.g., days 1-180, limit 1-200, event_type exact match). However, it does not mention the user_intent parameter or the required brand_id beyond a parenthetical, leaving some gaps.

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 ('Read the in-product activity feed for the brand') and elaborates on what the feed contains. It distinguishes itself from siblings like get_actions or get_changes by framing the feed as the unified event timeline and providing the answerable question.

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

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

Gives a clear context ('Use this to answer what's happened with my brand lately?') and explains the two views with their filtering conditions. It doesn't explicitly exclude or name an alternative sibling, 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 already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context beyond annotations: this is a current per-brand set, not a time series, and an empty result is explanatory rather than retryable.

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 two sentences, and the Args block is scannable. Minor redundancy with the schema (repeating 1-365 and 1-200 ranges) costs a little, but nothing is wasted overall.

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 does cover the meaningful return behavior (the empty-set `note`). Combined with the effective annotation set, an agent has enough to call this correctly, though the absence of sibling routing leaves 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?

With 50% schema coverage, the description compensates well: it explains the semantics of `days` (only opportunities first found in the last N days, omit for current set), `limit`, and the legacy `brand` key compatibility. It omits any mention of the `user_intent` parameter, which the schema documents only thinly.

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 opportunities) and defines the concept precisely as citation gaps where competitors are cited but the brand is not. However, it never differentiates itself from close siblings like list_opportunity_pool or commit_opportunity, so an agent must infer which opportunity tool to pick.

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 operational context: leave `days` unset for the full current set (what the app shows), and empty results carry a `note` that retrying with different `days`/`limit` won't fix. It does not state when to prefer this over `list_opportunity_pool` or when to hand off to `commit_opportunity`.

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 readOnly/idempotent/non-destructive, so the safety bar is low. The description adds real behavioral context beyond that: a not-found error when no analysis exists within max_age_days, the deliberate refusal to refresh because it would consume LLM credit, and https:// normalization of the URL.

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

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

Front-loaded with the purpose, then return payload, then error/credit behavior, then args — a logical order with no filler. It is longer than strictly necessary, but each block carries distinct information.

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

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

With no output schema, the description usefully enumerates the returned payload (diagnosis, citation verdict, checks, schema, queries, facts, entities, bot visibility) and covers the error case and credit rationale. 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 only 25%, but the description compensates by documenting three of four parameters: brand_id (required), url (required, with normalization and the fallback lookup workflow), and max_age_days (1-365, default 30). The undocumented user_intent is already described in the schema, so coverage is effectively complete.

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 cached deep analysis for a single URL') and pins the scope with 'cached' and 'single URL'. This cleanly separates it from list_page_analyses (which lists many) and run_diagnosis (which produces a fresh analysis), so an agent can choose 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?

Gives explicit routing: if the URL is unknown, call list_page_analyses with the same brand_id and use a returned URL rather than guessing, and it clarifies that fresh analyses come from the dashboard rather than this call. The only gap is that it never names the run_diagnosis sibling as the programmatic path to a fresh analysis.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: that writes are deliberately unavailable here, how `period` overrides `days`, that only dashboard/metrics support periods, and that the response then carries a `period` block. Return-shape detail per view is lighter, keeping it at 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?

Front-loaded with the one-line purpose, then scoping constraint, then a consistent per-view list and an Args block, so an agent can scan to the exact knob it needs. It is longer than strictly necessary, with some prose (e.g., the narrative_drift entry) that could be tightened, but every section 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 six parameters, a single enum, and no output schema, the description supplies enough to call the tool correctly and anticipates the main return shape per view (scores, themes, excerpts, period block). It does not describe pagination or result limits, which is a minor gap for a read tool of this size.

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 only 17%, so the description must carry the load, and it does: it documents brand_id (required), the full view enum with per-value meaning, days with its 7-365 range and 90 default, the YYYY-MM / YYYY-Qn period format plus its override behavior and view restriction, and tracked_brand's metrics-only scope. That is substantially more than the schema 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 and resource ('Get brand perception analysis from AI models') and enumerates exactly what the analysis covers: sentiment, themes, narrative shifts, and competitive positioning. This separates it from siblings like compare_brands, get_narratives, and get_visibility_scores without the agent needing to open 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?

Each of the five 'view' values is described with the condition that selects it, and the description explicitly rules out a workflow ('Refreshing perception is intentionally not exposed; trigger that from the dashboard'). It stops short of naming a sibling tool as the alternative for overlapping cases, so it is clear context rather than full when/when-not 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 cover safety (readOnly, idempotent, non-destructive), and the description goes well beyond them: closed months are served from a frozen archive and answer identically later, the open month is MTD with status='open', quarters are derived from three months, and fields_missing tells the agent what to say is 'not reported'. It also discloses that response_format='concise' caps long lists and that deltas are precomputed with correct sign.

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

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

Well front-loaded and organized with Views, Examples, and Args sections, and the anti-drift warnings genuinely earn their place. It is on the long side and the Args block partially restates schema-adjacent content, but the length is defensible for an 8-parameter tool with no output schema.

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

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

With no output schema, the description still enumerates the return shape (period, prior period, metrics, breakdowns, headline_metric_ids, groups, metric_meta, period.status, period.fields_missing) and explains how deltas, directions, and ranks are already computed. Nothing an agent needs to call it 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 description coverage is only 13%, so the description must carry the semantics, and it does: period format (YYYY-MM / YYYY-Qn, omit for most recent closed month), view contents for each enum value, compare default, include_definitions content, months (list-only, 1-36, default 12), and response_format behavior. Seven of eight parameters are richly documented, far exceeding what the schema provides.

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

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

States a specific verb and resource ('Get one frozen calendar month or quarter: the whole client report in one call') and explicitly distinguishes itself from rolling/days-window reads. An agent immediately knows this is the canonical calendar-period report tool, not a daily-series tool.

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

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

Gives explicit when-to-use ('THE tool for any calendar-month or quarter figure and for a monthly or quarterly client report') plus a clear when-not ('Never approximate a month with days=30 or days=31; the window slides and the figure drifts'). It also tells the agent to use view='list' first to see what is frozen before requesting it, which is real 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?

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile is covered. The description adds useful ranking semantics (impact-ordered output) and default limit, but says nothing about pagination, ordering ties, or latency for a portfolio-wide rollup. With annotations carrying the safety burden, a 3 is appropriate.

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 lead sentence delivers the core purpose up front, followed by a short scoping paragraph and a compact args block. Slightly redundant wording in the parenthetical brand-group clause, but no sentence is wasted.

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

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

For a read-only rollup with no output schema and 4 params at 25% coverage, the description covers scope, ranking intent, group filtering, quick_win semantics and limit bounds. The one real gap is user_intent, which appears in the schema but is never mentioned in the description, so an agent gets no hint about what analytics hint to pass.

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 low at 25%, so the description must compensate: it explains group_id as an optional brand-group filter, quick_win as high-impact/low-effort filtering, and limit as 1-200 with default 50. It omits any explanation of the user_intent parameter, leaving one of four parameters undocumented in prose, which caps it below 5.

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

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

The description states a specific verb and resource: rolling up the unified action queue across all brands, ranked by impact. It distinguishes itself from get_actions by emphasizing the portfolio/multi-brand scope and the agency use case, though it never names get_actions as the narrower single-brand alternative, leaving that inference to the reader.

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 agency framing ("what should I work on first today, across every account?") gives a clear context for when to reach for this tool, and the group_id arg narrows it to a brand group. It stops short of explicit when-not-to-use guidance or naming a sibling, so it is clear context without exclusions.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description goes beyond that by enumerating the exact payload surface (config fields, allowed crawlers, requests so far, limit, percent used, reset date) and the negative space, which is genuinely useful behavioral context for a quota-state tool. It stops short of stating auth requirements or rate limits on the call itself, so it is not a 5.

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

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

Front-loaded: the one-line purpose and the setup-vs-analysis framing come first, followed by the payload inventory and the negative-space routing. The closing Args block is somewhat redundant with the schema's required list, which is the only waste in an otherwise tight definition.

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

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

There is no output schema, so the description must carry the return-value burden — and it does, enumerating every field group returned. Combined with the explicit exclusions and sibling routing, an agent has everything needed to select and call this correctly.

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

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

Schema description coverage is 50%: user_intent is documented in the schema, but brand_id has no schema description, and the description's 'brand_id: The brand to check (required)' is only marginally more informative than the field name plus the required list. The description does partially compensate for the coverage gap, which is the minimum bar, but adds no format or constraint detail.

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 brand's AI Pages connection state and monthly usage') and immediately frames the scope ('This is setup and quota, not analysis'). It explicitly names the sibling tools that cover adjacent purposes (get_perception, get_actions), so an agent can distinguish it from the other 60+ tools without opening a schema.

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

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

The description gives an explicit when-not ('It does NOT return positioning, strengths, weaknesses, opportunities, or themes') and routes the agent to the correct alternative for each excluded need ('for how AI describes the brand use get_perception; for recommendations use get_actions'). That is a complete decision rule, not an implied one.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds genuinely new context by disclosing the tool's legacy/deprecated alias status, but says nothing about return content, pagination, or filtering behavior.

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, zero filler, and the most decision-relevant fact (legacy alias, prefer get_results) is front-loaded. Nothing could be removed without losing meaning.

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 deprecated alias whose main job is to redirect agents to get_results, the description is arguably sufficient at the routing level. But with 7 under-documented parameters and no output schema, an agent that must actually invoke this tool gets no help understanding its behavior or arguments.

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

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

The schema has 7 parameters with only 14% description coverage, and the description contributes no parameter information at all. With low schema coverage, the description was expected to compensate and instead provides zero guidance on brand_id, days, limit, cursor, family, verdict, or user_intent.

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 identifies the tool as a 'legacy alias for get_results,' which tells the agent what it fundamentally is and differentiates it from the modern sibling. However, it never states the actual verb+resource or what data is retrieved, so the domain purpose is only implied through delegation to get_results.

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

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

It explicitly routes new integrations to get_results, which is a clear alternative and an implied when-not to use this tool. It stops short of a full 5 because it never describes the legacy scenario in which using get_proof is still appropriate.

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

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

Annotations already declare readOnly/idempotent/non-open-world, and the description adds real behavioral context beyond them: days_effective reporting, period-archival 'not found' behavior, nulled fields, and the semantics that LOWER position is better while a positive position_change means the brand slipped.

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

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

Front-loads the purpose, then organizes the rest into a Views list and an Args list, so scanning is easy. It is fairly long, but nearly every line carries parameter or behavioral meaning; only marginal trimming is possible.

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 an 8-parameter tool with 13% schema coverage and no output schema, the description supplies the missing parameter semantics plus key response-field behavior (days_effective, period block, win_rate/threat_count nulls). Nothing needed 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 only 13%, so the description must carry the load and it does: it documents brand_id, view, days (with per-view clamping: overall <=90, prompt-trends 7-90), period (overrides days, overall-only, null win_rate/threat_count), include_volume, tag_ids and limit. Only the schema-documented user_intent is absent. This far exceeds 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 competitive ranking data in AI search results') with scope ('across all tracked prompts and AI models'). It does not explicitly contrast itself with nearby siblings like get_visibility_scores or compare_brands, so it stops 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?

Gives clear context ('understanding competitive positioning') and, crucially, tells the agent which view answers a specific question ('prompt-trends ... answers which specific prompts are being lost and since when'). No explicit when-not-to-use guidance or named alternatives, so not a 5.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds semantic context about what Reddit data is for (AI citation surfaces, mention/sentiment/threads), which is useful, but discloses nothing about pagination behavior, ordering, or the cost of large page_size/days values.

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 a one-line purpose, then a bulleted view list and a compact Args block — structure matches how an agent scans. The opening paragraph about Reddit as an AI citation source is mild framing rather than operational instruction, so it is slightly longer than strictly necessary, but no sentence is confusing or 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?

For an 8-parameter, no-output-schema read tool, the description supplies what is missing from structured fields: per-view return content (weekly stats, comment tree, sentiment trend), conditional parameter rules, and filter applicability. Safety is covered by annotations. Only return-size/pagination expectations are unstated, so it is nearly complete.

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

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

Schema description coverage is only 13% (just user_intent), so the description must carry the load, and it largely does: it documents brand_id, view, thread_id (with the conditional 'Required for view=thread'), status values, which views accept subreddit, and the days/page_size defaults. It even adds a format rule not in the schema ('no r/ prefix' for subreddit). It falls short of 5 only because numeric bounds are left to 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?

The description names a specific verb (Read) and resource (Reddit monitoring data for the brand) and enumerates the seven views, so an agent knows exactly what slice of data comes back. It does not, however, explicitly distinguish itself from read-only siblings like get_opportunities or write-path siblings like manage_reddit_opportunity and scan_reddit, leaving that inference to the reader.

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?

Each view carries its own usage context: 'opportunities' is for threads the brand hasn't appeared in, 'thread' requires thread_id, 'feed' is chronological mentions. That is clear when-to-use guidance. It stops short of 5 because it never states when not to use this tool or which sibling to prefer for adjacent needs (e.g., managing vs reading Reddit records).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint, so the safety profile is covered. The description adds meaningful behavior beyond that: report IDs are never derived from brand_id, view selection changes required inputs, and response_format='concise' deliberately caps arrays and drops verbose dumps to protect 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?

The description is long but appropriately so for a 10-parameter tool with four view modes. It is front-loaded with purpose, the input requirement, and the critical report_id warning, then organized under Views and Args headings with no evident 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?

Given the lack of an output schema, the description still explains what each view returns at a useful level: list metadata, detailed visibility results, sentiment analysis, and mention counts over time. It covers prerequisites, pagination parameters, defaults, and context-protection behavior sufficiently for correct invocation.

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

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

Schema description coverage is only 10%, so the description carries the burden and does so well: it documents brand_id, report_id, view, report_type, status, days, limit, offset, and response_format with meanings, defaults, constraints, and conditional requirements. Only user_intent is absent from the description prose, and the schema itself provides its description.

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 reports or retrieve a specific report') and distinguishes the two modes clearly. The view list further separates the possible data operations, so an agent can tell what this tool does 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 requires at least one of brand_id or report_id, explains that report IDs are not guessable and must come from view='list', and gives per-view prerequisites. It also advises using report_id with a specific view for large reports, which is actionable 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the gating behavior: topic snapshots are capped by a monthly limit on the account. That rate-limit context is genuinely useful, though it says nothing about what the response contains (used vs remaining credits), which would help since no output schema exists.

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

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

Front-loaded with the purpose, then the gating context, then the prerequisite call, then args. The structure is efficient and scannable, with only mild redundancy between the first sentence and the monthly-limit sentence.

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

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

For a simple read-only getter with no output schema, the description covers purpose, gating behavior and the required parameter well enough to invoke correctly. The main remaining gap is the response shape (what credit figures are returned), which the agent must discover by calling.

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 50%: the schema documents user_intent but leaves brand_id bare. The description documents brand_id as 'the brand to check (required)' but adds nothing for user_intent, so it only partially compensates for the coverage gap. 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 with scope: it retrieves the brand's topic snapshot credit usage for the current month. An agent can distinguish it from other get_* tools because credit/quota checking is its unique subject, and it explicitly positions itself relative to run_research_snapshot.

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 prescribes the calling condition: 'Call this before run_research_snapshot to confirm credits are available.' It names the alternative tool and the decision it informs, leaving nothing to inference about when this tool is appropriate.

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 the safe read-only, idempotent profile, so the description correctly spends its budget elsewhere. It discloses genuinely useful behavior: results are paginated, 'concise' caps the per-prompt array to a readable head while 'detailed' returns the whole page, and both stay under a response ceiling.

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

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

Front-loads the purpose, then details return fields, then paging, then Args. Well-organized and every section is functional, though the long enumeration of returned fields is slightly heavier than needed since there is no output schema to lean on.

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

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

With no output schema, the description fully compensates by enumerating the returned fields and per-result shape. Combined with pagination guidance, the response_format tradeoff, and annotations covering the safety profile, an agent has everything needed to call it correctly.

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

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

Schema description coverage is only 20%, so the description must carry the load, and it does: it documents run_id, the 1-500 range and default 100 for results_limit, the offset default for results_offset, and the semantic difference between the concise and detailed enum values. Only user_intent is left to the schema's own description.

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

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

States a specific verb and resource ('Get a single prompt research run') and immediately scopes the payload as 'the full analytics payload'. The singular 'a single run' and the pointer to get_research_runs for IDs clearly distinguish it from the plural list sibling.

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 usage context: retrieve one run by ID, fetch IDs from get_research_runs, and use results_limit/results_offset to page because runs routinely hold 500+ entries. It does not compare against adjacent siblings like get_latest_research, so it stops short of full when/when-not guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so safety is covered. The description adds meaningful behavior beyond that: results are newest-first, and 'ready_only' defaults to true so only successfully completed runs are returned by default, which is a real filtering trap for an agent. It does not cover auth requirements or rate limits, keeping it out of the 5 range.

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 one line, then the returned-field summary, then the Args block. Every sentence is functional. The metrics enumeration is a long list, but with no output schema it is load-bearing rather than filler.

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

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

With no output schema, the description usefully enumerates what each run summary contains (visibility score, mention rate, brand rank, competitors, topic context) plus all filtering and pagination controls. Nothing critical to invoking it correctly is missing, though the relationship to get_research_run remains 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 description coverage is only 17%, so the description carries most of the parameter burden and largely delivers: brand_id (required), report_type enum values, ready_only semantics, and limit/offset ranges and defaults are all spelled out. Only user_intent is undocumented here, though the schema itself covers that one, so semantic compensation is strong but not exhaustive.

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 with ordering: 'List prompt research runs for a brand (newest first).' An agent immediately knows this is a collection-retrieval tool. However, it never differentiates itself from the very similar siblings get_research_run (singular) or get_latest_research, 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 explains how each filter narrows the result set (report_type, ready_only default of true, pagination), which implies usage. It does not, however, state when to pick this tool over get_research_run, get_latest_research, or get_reports, leaving the agent to infer the 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?

Beyond annotations (readOnly, idempotent, non-destructive), the description discloses what the data actually is: pipeline-computed, not self-reported, over a frozen window, and explicitly non-causal ('says a metric moved, not that the change caused it'). It also defines each verdict's meaning and the harm reporting convention, which is exactly the behavioral context an agent needs to interpret results.

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

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

Front-loaded with the core semantics, then cleanly sectioned into Verdicts, Recipes, and Args, so an agent can stop early. It is somewhat long, but each block (verdict glossary, causal disclaimer) earns its space; no padding stands out.

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 7-param read tool with no output schema, the description covers selection, filtering, pagination, and interpretation semantics well. It does not describe the shape of a returned row beyond the verdict vocabulary, and the cursor's meta.next_cursor is only implied, 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?

With schema description coverage at only 14%, the description carries the load and does so: it documents brand_id, the four verdict values with their interpretations, family as a verb-family narrowing, days as a 1-3650 window, limit 1-200 default 50, and cursor as an opaque meta.next_cursor token. Only user_intent is undocumented here, and that one carries its own schema description.

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/resource: measured before-and-after change from completed work, computed by the pipeline. This is distinguishable from siblings like get_changes or get_actions, though the description never explicitly contrasts them, so the agent must infer the boundary from recording semantics.

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 'Common recipes' block gives concrete call patterns ('Did our work pay off', 'What went backwards') that map intent to invocation. It lacks explicit when-not-to-use guidance or named alternatives among the many sibling get_* tools, so it stops short of 5.

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

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

Annotations already cover readOnly/idempotent/non-destructive/open-world, so the description correctly spends its budget on non-obvious traits: the auth prerequisite, the assurance that Google credentials stay in Trakkr and are never returned, and an important semantic caveat that position is an average across recorded impressions rather than a fixed SERP rank. No return format or pagination detail, but the schema/annotation coverage keeps the bar low.

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 prose paragraph is front-loaded and each sentence earns its place. The Args block is mildly redundant, restating url and days semantics already stated above, but it is compact and not 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 return-value burden and does so by listing the metric set and the top-pages/queries scope. Combined with the auth prerequisite and position caveat, an agent has everything needed to call this correctly.

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

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

Schema description coverage is only 20%, so the description must compensate and largely does: it explains brand_id (required), url omission vs page URL behavior, days as an inclusive 1-90 window with default 28, and compare_previous_period as equal preceding period with deltas. Only user_intent is left entirely to 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?

Opens with a specific verb+resource ('Get Google Search Console performance') and immediately names the data source (Trakkr connection). The second sentence enumerates the exact metrics returned (clicks, impressions, CTR, average position), which differentiates it from generic siblings like get_traffic or get_rankings.

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 concrete when-to-use guidance for the key parameter branch (omit url for property-wide top pages/queries, pass a URL for page-level aggregates) and states the prerequisite that the brand must have connected Search Console in Trakkr. It does not, however, name any sibling tool as an alternative for adjacent metric needs.

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?

Given annotations declare readOnlyHint and destructiveHint, the description adds valuable context beyond that: it explains that results come from regular reports with rolling refresh (delays possible), that no AI runs are made, and clarifies the semantics of 'brand_in_answer' (null means not established, not no). This is useful behavioral context not in the schema or annotations.

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

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

The description is well-structured with a clear opening line, a detailed explanation of what is meant by 'tracked articles' and the output fields, and a separate arguments section. It is somewhat lengthy but each sentence adds value, and it avoids fluff. The main behavior is front-loaded, with the distinction from get_articles placed near the end for clarity.

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

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

For a read-only tool with no output schema, the description covers the key aspects: what the tool returns (fields like article_cited, previously_observed, providers, brand_in_answer), the meaning of null, the data freshness caveat, and the distinction from the sibling. It lacks detail on pagination or sorting, but given the complexity, it is fairly complete.

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

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

Schema coverage is only 33%, with the domain parameter having no description. The description explains domain as 'Only articles on this domain, e.g. resources.example.com', which adds crucial meaning beyond the schema. brand_id is described as 'The brand to read', which is minimal but sufficient. user_intent is not described but is an analytics hint, and the description's focus on the other two parameters compensates for the low schema coverage.

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

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

The description clearly states the tool reads the brand's tracked published articles and whether they are cited in AI answers, distinguishing it from get_articles which lists drafts. It is specific about the resource (tracked articles) and the action (read).

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

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

The description explicitly differentiates from the sibling get_articles, noting that get_tracked_articles is for tracked published articles, not drafts. It also mentions the rolling refresh cadence, which helps set expectations on when to use it (e.g., not for real-time checks).

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

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

Annotations already declare readOnly, idempotent and non-destructive, so the safety profile is covered. The description still adds real value beyond them: the setup prerequisite for traffic tracking and the fact that data is 'live' rather than historical.

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, then clean 'Views' and 'Args' sections; each line maps to a distinct parameter or mode. Slightly redundant to restate defaults/ranges already in the schema, but no sentence is wasted.

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

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

For a read-only analytics tool with no output schema, the description covers purpose, prerequisite, view semantics, and parameter defaults adequately. The remaining gaps — what each view actually returns and how user_intent is used — are minor.

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 only 25%, so the description must carry the load, and it does for three of four params: brand_id (required), view default/meaning, and days default plus 1-365 range. It omits any mention of user_intent, leaving that one parameter documented only by 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?

Opens with a specific verb+resource ('Get live traffic data for a brand's website') and narrows scope to AI-search-engine referrals, visitor counts, sources and trends. An agent can distinguish this from crawler siblings like get_crawler_live or get_search_performance, though the description never names a sibling to sharpen that contrast.

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

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

It gives the prerequisite ('Requires traffic tracking to be set up') and explains the three view modes, which implicitly steers selection. However, there is no explicit 'use this instead of X when...' routing against the many sibling report/analytics tools, 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 already declare readOnly=true, idempotent=true, destructive=false and openWorld=false, so safety is covered. The description adds non-obvious behavior: supplying period causes days to be ignored and adds a `period` block to the response, and it documents mutual-exclusion constraints. It stops short of describing pagination or output shape.

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

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

Front-loaded one-line purpose, then a scannable Views block and Args block. Each line earns its place, though defaults and enum values are restated from the schema, which is mild redundancy rather than bloat.

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 7-parameter read tool with no output schema, the description is nearly self-sufficient: it explains what is returned (overall score, presence rate, historical trend) and how period interacts with the response. Only the undocumented user_intent analytics hint and any result-size/pagination behavior are left 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 description coverage is only 14% (just user_intent), so the description carries the semantic load and does it well: brand_id required, view enum meanings, days lookback range 7-365 with default 90, period format YYYY-MM or YYYY-Qn, tag_ids comma-separated, and prompt_id single-prompt filtering. This meaningfully exceeds the bare 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?

Starts with a specific verb+resource ('Get AI visibility scores and trends for a brand over time') and frames itself as the 'how are we doing?' tool, which gives an agent a clear mental model. It names the four views, which scopes what the tool covers. It only partially differentiates from close siblings like get_model_breakdown, get_rankings, or get_perception.

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 view list effectively tells the agent when to pick each mode, and the period note explicitly states it 'cannot be combined with tag_ids or prompt_id' and routes whole-month use to get_period_summary. That is strong conditional guidance, though it does not contrast against the broader set of overlapping analytical siblings such as get_model_breakdown.

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, idempotentHint=true, destructiveHint=false, so safety is covered. The description adds useful domain context (triggers, actions, firing behavior) but does not address rate limits, pagination interaction with runs, or return shape. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Front-loads the purpose, then the domain model, then the views, then args. The view list is the densest value and is well structured. The 'Args' section duplicates some schema info but is justified given the low schema coverage.

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 multi-view read tool with 9 params and 11% schema coverage, the description fills most gaps: view behavior, conditional params, filters, and window. Missing only user_intent semantics and how pagination behaves for 'runs' vs 'list'. No output schema, so return-value notes are correctly omitted.

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 only 11%, so the description must compensate, and it largely does: it explains view semantics, conditional requirements (workflow_id for 'get', run_id for 'run_detail'), the days window (1-90, default 30), and filtering by status. It does not document user_intent, and the offset/limit ranges are only in schema.

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

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

States a specific verb+resource ('Read workflow automation state') and immediately explains what workflows are and what this tool surfaces ('see what's configured and what's fired recently'). The five-view breakdown makes it unmistakably distinct from the sibling manage_workflow (which writes).

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 maps each view to a purpose and names the required parameter for each ('get' requires workflow_id, 'run_detail' requires run_id). An agent can pick the correct view without reading the schema.

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