Sellular

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

Goes well beyond the annotations by disclosing that an admin token is required and that it bills per search, plus the important caveat that results are a retrieval proxy for citation rather than any model's answer. It also says the retrieved pages are returned so claims can be verified. What's missing is any note on latency, result volume, or failure behavior for the searches themselves.

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 question it answers and then the differentiator, with no filler paragraphs. A few phrases are persuasive rather than informational ('which is the gap a clean site can still have', 'you are holding the page and are far better placed'), costing some tightness.

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 the necessary work of saying it returns retrieved pages per query, and it covers cost, auth, and interpretation limits. An agent has enough to call it correctly; only result shape details (per-query grouping, counts) are left implicit.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: why `queries` should be natural buyer phrases, that the category enum exists only to build weaker fallback queries, and rough guidance via the schema's max of 4. It doesn't discuss `domain` handling (bare domain vs full URL) because the schema already does.

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?

Frames the operation precisely as live web retrieval for buyer queries that reports which pages answer them and whether this domain is among them. The contrast sentence ('Every other tool here reads the site's own bytes; this reads the market around it') cleanly separates it from the scan/audit siblings without naming each one.

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 instructs to pass `queries` with real buyer phrases, gives two concrete example phrases, and states the category fallback is 'deliberately weak' so the agent knows which path to prefer. It also carves out two negative cases (does not name rival brands, does not report ChatGPT answers) that stop the agent from using it for those jobs.

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

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

Goes well beyond the annotations: declares 'Admin token required; it bills per search,' discloses the internal heuristics and their fallibility ('they ARE heuristics and you must be able to overrule them'), and pre-empts a misread of null contactUrl ('means those four paths 404ed, not that the site cannot be reached'). Also sets negative expectations ('does NOT rank by authority and does NOT predict whether a pitch will land'). Fully consistent with readOnlyHint=true — it only searches and probes.

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 correctly, but the body is a single dense paragraph that packs return-value detail, heuristic caveats, and strategy advice into long compound sentences. Nearly all content is substantive, yet the structure makes it harder to scan than it needs to be for a tool with four optional parameters.

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

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

There is no output schema, and the description compensates fully by naming every returned field (`evidence`, `discussions`, `skipped`, `contactUrl`) and its semantics. Auth, cost, caching implications, and failure modes are all covered, so an agent has everything needed to call it and interpret results correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds only mild extra meaning — that maxHosts governs the contact-route probing and that queries feed the searches — without explaining formats, ordering of `queries`, or when category fallback degrades quality beyond what the schema already says.

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 concrete verb and resource ('Who could publish a page that names this site') and then explains the mechanism: it runs answer_engine_gap, filters to roundup-style slot-holders, dedupes per host, and probes for a contact route. It explicitly distinguishes itself from the alternative deliverable ('the list of people to ask rather than another page to publish'), so an agent can tell it apart from answer_engine_gap or a comparison-page workflow 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?

'Use when a site appears in none of its buyer queries' gives an explicit triggering condition, and the comparison-vs-roundup framing explains why you'd pick this over publishing. It even sequences the consumption of results ('Read `discussions` first when the roundups all sell placement'), which is rare and actionable.

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

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

Goes far beyond the annotations: discloses that the tool performs no upload itself, that it returns per-file curl commands valid for ten minutes and scoped to one product, that re-sending corrects rather than duplicates (consistent with idempotentHint=true), that nothing is deleted (consistent with destructiveHint=false), and that an MCP_API_KEY bearer token plus a confirmation step are required.

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 blocking value and the multi-directory payoff are front-loaded, and the operational caveats follow in a sensible order. Slightly padded – 'IMPORTANT: this tool uploads nothing by itself and cannot' is largely restated by the next sentence about the remote server.

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

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

There is no output schema, and the description compensates by explaining exactly what is returned (a curl command per file, ten-minute validity, product-scoped). Auth, confirmation, and idempotency semantics are all covered, so an agent can call this correctly without further context.

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

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

Schema coverage is 100%, so baseline is 3. The description adds constraints the schema does not carry: the 3-5 image count, PNG/JPG format, and 1280x720 minimum that directories demand, which gives the agent a way to validate inputs before calling.

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

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

Names a specific verb and resource ('attach real product screenshots ... to one of your tracked products') and immediately ties it to the two sibling tools it feeds (check_submission_readiness, generate_submission_kit), so it is distinguishable from every other sibling in the list.

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?

States the triggering condition clearly: use this when readiness/kit output reports screenshots missing. It also rules out a whole class of misuse ('never fetches, generates, resizes or substitutes'). It stops short of naming an alternative tool for the cases where the agent has no local files, so it is not a full when/when-not/alternatives treatment.

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?

Discloses behavior beyond the annotations: partial-success semantics ('returns partial results with a per-domain error instead of failing the whole batch'), rate-limit cost ('debits the rate limiter once per domain'), and caching ('results cache 24h per domain'). These are exactly the traits readOnlyHint/idempotentHint cannot convey. Slightly short of 5 only because failure modes for invalid or private domains beyond the per-domain error shape aren't described.

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

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

Four tight sentences, front-loaded with capability then constraints, cache, and use case — almost no waste. Minor redundancy: the cap of 10 is stated in the description and enforced by the schema, and the score range partially duplicates the stated output.

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

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

With no output schema and no annotations covering batching, rate cost, or caching, the description supplies all of them plus the return fields (score, grade, llms.txt presence). An agent has everything needed to call it correctly and predict its cost.

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

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

Schema coverage is 100% (the domains array is fully documented with 1-10 items, min length 3), so the schema carries the heavy lifting. The description adds the meaningful 'public' qualifier and restates the 10 cap, but provides no syntax guidance for the domain-vs-full-URL choice beyond what the schema already says. 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 ('Scan up to 10 public domains in one call') and enumerates the exact outputs per domain (visibility score 0-100 with A-F grade, llms.txt existence). It explicitly carves itself out from scan_domain ('No directory coverage'), so an agent can distinguish it from the sibling without opening either schema.

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

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

Gives a positive use case ('outreach research across a prospect list') and routes the alternative explicitly ('No directory coverage (see scan_domain)'). When/when-not guidance is present with the sibling named, leaving nothing 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' read-only/idempotent hints, it discloses account scoping, the required MCP_API_KEY bearer token, and precisely what the response contains (per-directory present/derived-with-source/missing-with-fix, a deduped blocker list, and progress counters). The auth requirement is information annotations do not supply.

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 and the kit exclusion, and every clause carries content. It is dense for a single sentence-and-a-half but not padded; slight overload from stacking the return-value enumeration inline.

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

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

No output schema exists, so the description carries the return-value burden and does so thoroughly (per-directory status, derivation sources, deduped blockers, progress). Combined with the auth and scoping notes, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so limit, product, and directory_name are already documented in the schema, including the domain-authority sort and substring matching. The description adds no parameter-level detail beyond 'per directory', so the baseline of 3 applies.

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

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

Specific verb+resource ('check what is missing before ... can be submitted to directories') with an explicit scope constraint ('WITHOUT generating a full kit'), which cleanly separates it from the sibling generate_submission_kit. An agent can select it without opening any schema.

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

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

States the exact decision contexts it serves ('what is missing' or 'where should submissions start') and the sequencing rule ('before doing any submission work'), plus the negative case of not building a kit. Alternatives are implicitly routed via the sibling name.

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 openWorld behavior, so the safety profile is covered. The description adds that only public sites are accepted and that each result carries a grade plus top strengths/weaknesses, which is useful extra context. It doesn't mention cost, latency, or failure behavior for unreachable/private URLs.

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

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

Two tightly written sentences, front-loaded with the operation and scope before the use case. Nothing is wasted or repeated.

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 one-parameter, read-only tool, this is close to complete: the description covers the input scope, the ranking behavior, and the return payload, since there's no output schema. Minor gaps remain around error behavior and whether all URLs must be reachable.

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

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

There is only one parameter and schema coverage is 100%, so the schema already documents the 2-5 domain/URL constraint. The description's '2-5 public websites' mostly restates the schema, adding only the 'public' qualifier, so the baseline 3 applies.

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

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

States a specific verb pair (score, rank) plus the resource (2-5 public websites) and the output shape (grade plus strengths/weaknesses, side by side). This clearly separates it from get_visibility_score, which covers a single site, since comparability across 2-5 sites is stated 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?

'Use to benchmark a site against competitors and explain who wins and why' gives a clear usage context. It never names an alternative tool (e.g., get_visibility_score for a single site) or states 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 cover read-only/idempotent/open-world safety, yet the description still adds real behavior: it returns text rather than writing files, the calling agent must place it at public/llms.txt or web root, and it discloses the empirical caveat that answer engines largely do not read the file. That is exactly the kind of context annotations cannot carry.

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

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

Purpose and output location are front-loaded and every sentence is actionable, but the evidence paragraph (Google July 2025, Ahrefs 97%/137,210 domains) is dense and repeated in spirit two or three times ('not a visibility fix', 'not scored', 'promising a citation lift would be false'). Slightly over-tall for the single-parameter operation.

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 one-parameter generator with no output schema, it covers what is produced, where it should be written, what the human reviewer must check, and the expectation-setting caveat — nothing an agent needs to call or frame 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?

Only one parameter with 100% schema coverage, so the schema already documents accepted forms ('domain or full URL'). The description adds only indirect meaning via 'fetched metadata', which implies the tool fetches the site rather than using supplied page data, but gives no format or validation detail beyond the schema.

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

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

States a specific verb and artifact ('Generate an llms.txt file body') plus the source ('from its fetched metadata: site name, description and key pages'), which clearly separates it from siblings like generate_seo_fixes or generate_submission_kit that also produce files.

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 use condition ('Use when the user asks for the file knowing that'), an explicit non-use framing ('it is not a visibility fix, it is not scored by get_visibility_score'), names a sibling, and adds a procedural prerequisite ('reviewing the Key Pages list 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?

The annotations already declare readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the mutation and external-call profile is partly covered — but the description goes well beyond with the publish guardrail ("NEVER published by this tool"), the editor email hand-off, the /reviews/[slug] destination, plan gating and quota spend. The one weak spot is a tension with idempotentHint=true: each call "counts against the monthly review generation quota" and "still spends the generation", so repeating a call appears to have a cost the idempotency hint does not convey. That is not a flat contradiction, but it is left unexplained.

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 not-published guarantee come first, then modes, then auth and preconditions — good front-loading given the complexity. It is long and has some overlap between the `hold_as_draft` narrative and the schema description of the same parameter, but for a nine-parameter, quota-consuming, multi-step tool the length is largely earned.

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

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

With no output schema, the description supplies the return values itself — preview link and the name of the waiting editor — and covers auth (product API key vs admin key plus product_id), plan requirement, quota cost and the approval lifecycle. Nothing an agent needs before calling it is missing.

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

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

Schema coverage is 100%, so the schema already documents every parameter, and the baseline would be 3. The description earns the extra point by explaining the relationship between parameters that no single schema entry can show: brief_only produces the matrix, which feeds `draft` on the second call, and `draft` bypasses the built-in writer while keeping the comparison table, cards and editor hand-off.

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

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

Opens with a specific verb and artifact — "Generate a competitor review article" — scoped to "one of your apps" identified by website or id. This is clearly distinguishable from siblings like generate_seo_fixes, list_my_reviews or generate_submission_kit, and it names the two identifier inputs up front.

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 spells out three explicit operating modes with the conditions that select each: brief_only for a human/model-written article, hold_as_draft to skip editor involvement, and the default submit-for-approval path. It also says when to use `rivals` (overriding live search) and `fills` (rows research could not confirm), plus the paid-plan and quota preconditions.

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, and destructiveHint=false. The description adds useful behavioral context by clarifying that Sellular's side is read-only and the tool itself writes nothing, despite producing ready-to-apply fixes. It also describes the deliverables and their placement in the source tree, going beyond the annotations' safety profile.

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

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

The purpose and output artifacts are front-loaded, followed by the agent workflow and the diagnosis alternative. Every sentence contributes specific information: examples of files, snippet types, source-tree placement, operational steps, and read-only clarification. No filler.

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

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

With no output schema, the description carries the burden of explaining deliverables and does so concretely by naming the file bodies and HTML snippets produced. It also explains where fixes belong and how to verify them, which is sufficient for a coding agent to invoke and use 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 100%, and the single url parameter is already documented as accepting a domain or full URL. The description adds contextual framing about building fixes for a public site but does not add syntax, format, or validation details beyond the schema. Baseline 3 is appropriate.

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

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

The description uses a specific verb and resource: turning failing SEO/AI-discoverability checks into ready-to-apply fixes. It enumerates the exact artifact types produced (robots.txt, sitemap.xml, llms.txt, HTML head snippets) and distinguishes the tool from seo_audit_summary by framing that sibling as the diagnosis-only alternative.

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 an explicit workflow: write the files, insert snippets, replace TODOs, deploy, then re-run seo_audit_summary to verify. It also states when not to use it: 'Run seo_audit_summary first when you only want the diagnosis.' This clearly routes the agent between generation and auditing.

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/openWorld, but the description adds real behavioral context: account scoping via MCP_API_KEY bearer token, the fields/copyText vs requirements split, blocker reporting and recorded progress. It doesn't discuss error modes or the ambiguity case when multiple products match, which keeps it from a 5.

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

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

Purpose is front-loaded in the first clause, then capabilities, then the read-only and auth caveats. It is dense but nearly every clause carries information; the mid-sentence run-on listing of output elements could be tightened.

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

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

With no output schema, the description usefully documents the return shape (fields/copyText, requirements, assets with provenance, blockers, progress) and the auth requirement. Minor gaps remain around behavior when no product matches or when multiple products match. Overall sufficient for correct invocation.

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

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

Schema description coverage is 100%, so the schema already explains limit, product, automation, signed_out, directory_name and remaining_only in detail. The description adds no per-parameter meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and artifact ('Build ready-to-paste directory submission copy') and enumerates what the kit contains (name, tagline, descriptions, category/pricing mapping, requirements, blockers, progress). The explicit 'Read-only formatter: it does NOT submit anything anywhere' cleanly separates it from write-side siblings like record_submission.

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 trigger: 'Use when preparing directory submissions without opening the dashboard,' reinforced by the read-only framing that implies record_submission handles the actual submission. It doesn't name an alternative sibling explicitly 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?

The description adds substantial behavioral context beyond annotations: it discloses that the badge auto-upgrades by tier and that its link resolves dynamically per click to either a featured article or the directory page. It also specifies an authentication requirement (MCP_API_KEY bearer token) and a constraint (never pin a width), and confirms 'edits nothing' consistent with readOnlyHint.

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

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

The description is front-loaded with the core purpose and then provides behavioral and usage details in a logical flow. While every sentence carries useful information, it is slightly verbose (a paragraph for a simple retrieval tool) and could be trimmed 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?

Given the tool's complexity (dynamic badge behavior, auth requirement) and the absence of an output schema, the description completely covers what is returned (HTML and Markdown), how the badge behaves, and what the caller should do with the result. No critical gaps remain for an agent to invoke it correctly.

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

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

Schema description coverage is 100%, so the parameter is fully documented in the schema. The description adds only slight context ('one of the connected account's products') without supplementing the substring match, optional behavior, or other semantics already present 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?

The description states a specific verb (get) and resource (the Sellular badge embed) plus the output formats (HTML/JSX and Markdown). It distinguishes this tool from siblings by focusing solely on badge embed retrieval, with no other tool in the sibling list serving that purpose.

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 what to do with the result: agents working in the product's source repo should add the snippet to the landing page, otherwise hand it to the developer. However, it doesn't explicitly mention when to choose this tool over alternatives (e.g., generate_submission_kit or generate_llms_txt) or any exclusions, leaving some inference to the agent.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the extra detail that matters is the auth requirement ('requires the MCP_API_KEY bearer token') and the cost disclosure that breakdown 'runs a second, heavier aggregation.' 'Read-only' merely restates the annotation, and there is no mention of pagination or rate limits, keeping it just below the top band.

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 capability and metrics, then the breakdown guidance and auth note in a logical progression; nearly every sentence earns its place. Minor waste in repeating 'Read-only' and the account-scoping already implied by the product parameter.

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 fully compensates by enumerating the returned counters and the breakdown dimensions (referring hosts, channels, campaigns, countries, devices, per-day trend). Auth, scoping, and the optional expensive path are all covered, so an agent can call it 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 coverage is 100%, so the baseline is 3; the description's contribution is mainly rationale — that breakdown answers 'why' while plain counters cannot, and that period is meaningless without breakdown. It does not add format or matching behavior beyond what the schema already documents for `product` (substring match) and `period`.

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 visitor analytics for one of the connected account's products') and enumerates the exact metrics returned (views, unique visitors for 7d/30d/all-time, published/draft review counts). An agent knows precisely what it retrieves, though it never names a sibling tool to contrast against (e.g. get_visibility_score or compare_visibility).

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 decision rule for the optional heavy path: 'ask for the breakdown whenever the question is why traffic moved or which source is working,' with the counter-case that counters alone cannot diagnose a spike. It stops short of stating when to prefer this tool over sibling analytics tools, so no full alternative routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and openWorld, so the safety profile is covered. The description contributes beyond that by enumerating what is measured (meta tags, sitemap, llms.txt, structured data) and the result scale, which helps an agent set expectations.

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

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

Three tight sentences: what it returns, what it measures, and when to use it. Front-loaded and free of 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 supplies the score range and grading scale plus the signal categories. Minor gaps remain, such as whether scoring is synchronous or how long it takes, but an agent has enough 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?

Only one parameter exists and the schema documents it at 100% coverage, including the 'domain or full URL' format. The description's 'by domain or URL' merely restates the schema, so baseline 3 applies.

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

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

States a specific verb and resource: getting the Sellular visibility score for a site, and even defines the output shape (0-100, graded A-F). It does not explicitly distinguish itself from nearby siblings like scan_domain or seo_audit_summary, which keeps it from 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 a clear triggering condition: 'Use when asked how discoverable or SEO-ready a site is.' It doesn't name when-not to use it or point to alternative tools such as compare_visibility or scan_domain, so no explicit routing between siblings.

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, so the safety profile is covered. The description adds genuine value beyond that by stating curation scope and the domain-authority ordering, and by explicitly disclaiming side effects. It does not describe result shape or paging behaviour, which keeps it below a 5.

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

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

Three tight sentences: purpose and ordering first, optional filter second, read-only caveat and intended use last. Nothing is repeated from the schema verbatim and every clause adds information.

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

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

For a two-parameter, read-only reference list with no output schema, the description covers what the tool returns conceptually and when to use it. The main residual gap is the undocumented `limit` cap of 71 and any truncation behaviour, which an agent cannot discover from structured fields.

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 50%: `category` is documented in the schema and the description reinforces it with concrete examples ('saas', 'ai', 'tools', 'dev'). The `limit` parameter has no documentation anywhere, and the unusual maximum of 71 and its default of 25 are left unexplained, as is any paging behaviour.

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 curated directories a product can submit to, sorted by domain authority.' That is far more informative than the name alone. It never explicitly contrasts itself with near-neighbours like list_public_listings or list_tracked_sites, so the agent must infer the difference.

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 use case ('Use to suggest where a product should get listed') and an explicit exclusion by clarifying it is reference data only and does not submit anything. It stops short of naming the submission alternative or listing when-not-to-use conditions, so it is strong but not complete routing guidance.

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

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

Annotations already cover the read-only/idempotent profile, and the description adds a lot beyond them: deterministic ordering (newest first), the status lifecycle values, that editor notes and the public URL are surfaced once live, and concrete auth mechanics with two accepted key types. It also explains a non-obvious semantic — both keys return the whole account because reviews belong to the owner, not a single product.

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

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

Three sentences, front-loaded with the resource, scope and ordering before usage and auth. The auth sentence is long and carries a parenthetical navigation path, but that detail is operationally useful rather than filler.

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

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

No output schema exists, so the description shoulders the return-value burden and does so by naming the surfaced fields and ordering. Auth, scope and status vocabulary are all covered; the only remaining gap, pagination behavior, is low-stakes for a 2-parameter optional-filter list tool.

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

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

With 50% schema description coverage, the description should carry more weight. It restates the status enum values but says nothing about the `limit` parameter, defaulting, the 50 cap, or what happens when results exceed the limit — the one genuinely ambiguous dimension 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?

States a specific verb and resource ("List the review articles") plus scope ("across every product you own"), and enumerates what comes back: editorial status, editor notes, public URL. It implicitly separates itself from the sibling generate_review via "Use to check what happened to a generated review," though it never names a sibling 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?

"Use to check what happened to a generated review" gives a clear triggering context and implicitly contrasts with generate_review. There is no explicit when-not guidance (e.g. how to inspect a single review) and no naming of alternatives for narrower listings, which keeps it off 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?

Adds substantive behavior beyond the annotations: idempotency is scoped per domain, nothing is ever deleted (reinforcing destructiveHint=false), the card is a public page at sellular.online/community/<domain>, and it drives the Sellular badge link. It also discloses the auth requirement (bearer token) and the confirm-before-write step, which annotations alone do not convey.

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

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

Front-loaded with the action, followed by context (public card, badge), then the idempotency and never-deletes guarantees, then prerequisites and auth. Every sentence carries information, though five sentences is on the verbose side for a one-parameter tool.

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

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

No output schema exists, and the description compensates by describing the resulting artifact (a public card at a predictable URL) and the per-domain idempotency semantics. It stops short of stating what the response payload contains (e.g., the card URL or a created-vs-updated flag), which is the only notable gap for a mutation tool.

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

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

Single parameter with 100% schema description coverage: the schema already explains that product accepts an id, name, or domain with substring matching and is optional when the account tracks only one product. The description adds no syntax or disambiguation detail beyond that, so the baseline of 3 applies.

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

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

The description states a concrete action pair (publish a tracked product into the Sellular community directory, or refresh its existing card) on a named, well-scoped resource. It also pre-empts confusion with the misleading tool name 'list_product' by making clear this is a write/publish operation, and names the sibling (track_product) that produces the required input.

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

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

Use conditions are explicit and actionable: only already-tracked products can be listed, run track_product first for anything missing, and the call requires the MCP_API_KEY bearer token plus user confirmation before writing. What is missing is guidance on when to prefer the read-side siblings (list_directory_listings, list_public_listings) or get_listing_badge instead, so alternatives are partially but not fully covered.

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 'Read-only' in the description is largely redundant. It adds nothing about ordering, pagination beyond the limit param, or whether results are capped or truncated, which are the behavioral facts an agent still lacks.

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

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

Three short sentences, front-loaded with the resource and scope, with no filler. The only wasted clause is 'Read-only', which merely repeats the annotations.

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?

Three optional params, no output schema, and rich annotations mean the description needs to cover scope and filtering, which it does. Still missing is any hint of result shape or pagination, but that is a modest gap for a simple list tool.

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

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

Schema description coverage is only 33% — 'search' is documented in the schema while 'limit' and 'category' are bare. The description restates that category and search exist as filters but supplies no semantics for either (matching behavior, valid categories, pagination interaction), so it fails to compensate 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 ('List public community listings on Sellular') plus the two filter axes, which is clear enough to act on. It does not, however, distinguish itself from the very similar sibling list_directory_listings, and the phrase 'community directory' slightly muddies which list is which.

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 sentence 'Use to browse products already listed in the community directory' gives a positive usage context, but there is no when-not guidance and no pointer to alternatives such as list_directory_listings or list_product, which an agent would need to choose correctly.

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 and destructiveHint=false, so the safety profile is covered; repeating 'Read-only' is mildly redundant. The description does add value beyond annotations by disclosing the auth requirements (MCP_API_KEY bearer token plus MCP_ACCOUNT_EMAIL) and the account-scoped nature of the result set.

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

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

Three short sentences, front-loaded with the resource and its returned fields before constraints. Minimal waste, though 'Read-only' duplicates the annotation and could be dropped.

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 no-parameter, account-scoped list tool with no output schema, the description covers what is returned, the account scope, and the credential prerequisites. An agent has everything needed to decide to call it and to know it will succeed only with proper auth.

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 zero input parameters the baseline is 4; there is nothing for the description to disambiguate, and it correctly avoids inventing parameters. It does add light context by naming what the response carries rather than inputs.

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 — listing the sites/products tracked on the connected Sellular account — and enumerates the returned attributes (type, category, status, badge verification). The 'tracked on the connected account' scoping implicitly distinguishes it from siblings like list_public_listings and list_directory_listings, which cover public rather than account-tracked inventory.

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

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

Usage is implied: this is the tool for seeing what is already tracked on your account, which contrasts with track_product (adding) and the public listing tools. However, no sibling is named and there is no explicit when-to-use/when-not guidance or precondition statement beyond the auth requirement.

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=false and idempotentHint=true, but the description adds real substance on top: the idempotency key is product+directory, repeats update rather than duplicate, nothing is ever deleted, and it is account-scoped requiring the MCP_API_KEY bearer token with a confirmation prompt before writing. That is exactly the auth/write semantics the annotations cannot express.

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

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

Front-loads the action and its consequence, then the status vocabulary, then the non-submission caveat and auth note. Roughly 100 words with no filler, though the status-value list is stated twice (it also appears verbatim in the schema).

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

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

For a write tool with five optional-ish params, no output schema and partial annotation coverage, the description covers everything an agent needs: purpose, effect on sibling tools, idempotency semantics, non-destructiveness, auth requirement, and a confirmation expectation. Nothing material is left to inference.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns an extra point by defining the three status values in behavioral terms ('done or live', 'waiting on their review', 'turned down') and by explaining the composite idempotency key product+directory, which tells the agent how those two arguments interact. The product parameter itself is never mentioned, so it stops short of a 5.

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

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

The description uses a specific verb+resource ('Record that one of your tracked products has been submitted to a directory') and immediately names its downstream consumers, check_submission_readiness and generate_submission_kit, making the boundary with those siblings unambiguous.

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

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

It states exactly when to call it (after you've submitted to a directory), what it prevents (re-submitting the same place twice), and includes a hard exclusion: 'This does NOT submit anything anywhere; it only records what you did.' That disambiguates it from generate_submission_kit without the agent opening a schema.

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, openWorld, non-destructive, so the description earns credit for what they don't cover: results are cached 24h per domain and directory coverage is deliberately excluded for every domain, including the caller's own. What's missing is any note on failure behavior (unreachable domains, invalid input) or whether the target must be a tracked site.

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 deliverable and packed with useful content in three sentences, with no filler. It loses a point for the convoluted clause "Reports NO directory coverage, for any domain, including your own: that needs the account's submission records," whose emphasis is harder to parse than the rest.

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

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

With no output schema, the description must describe the return values, and it does: a 0-100 score with A-F letter grade plus llms.txt existence at two locations. Combined with the caching note and the explicit scope exclusion, an agent has everything needed to choose and call this tool correctly.

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

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

Only one parameter, and the schema already documents it at 100% coverage ("A domain (example.com) or full URL to scan"). The description adds nothing about accepted formats, normalization, or subdomain handling beyond that, so this sits at the baseline for fully-specified single-parameter schemas.

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 concrete verb+resource ("One-call visibility audit for a public website") and enumerates exactly what is produced: a Sellular visibility score (0-100, A-F) and llms.txt presence at root or .well-known. It also distinguishes itself from the sibling check_submission_readiness by name, so an agent can separate it from the other scan/audit tools without opening any schema.

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

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

Gives an explicit positive trigger ("Use when asked to audit or size up a site's overall discoverability in one shot") and an explicit negative scope with a named alternative ("Reports NO directory coverage... ask check_submission_readiness instead"). Both the when-to-use and when-not-to-use conditions are stated outright.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds useful context beyond that: the audit targets public URLs and failures are ordered by impact so the agent can recommend fixes. It stops short of describing rate limits, latency, or failure modes, but the added ordering and targeting details are 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?

Three short sentences, front-loaded with the core action and scope. Every sentence adds a distinct fact: what it does, what it returns and how it is ordered, and when to call it. No filler.

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

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

For a one-parameter read-only audit with no output schema, the description provides enough to call it correctly and interpret the result structure at a high level. It could say more about input requirements (e.g., accessibility of the URL) or typical runtime, but nothing critical is missing.

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

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

Schema coverage is 100% and the single parameter is already documented as a domain or full URL. The description adds only the qualifier that the URL must be public, which is a small but real semantic constraint. Baseline 3 is appropriate because the schema does most of the work.

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

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

The description states a specific verb and resource: a read-only SEO / AI-discoverability audit on a public URL. It also names the return shape (passing and failing checks sorted by impact), which distinguishes it from sibling tools like get_visibility_score or generate_seo_fixes without opening either schema.

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

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

It gives explicit sequencing: use after get_visibility_score to explain a low score. That is a clear condition and names an alternative, but it does not state when not to use it or mention other related siblings such as generate_seo_fixes.

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 real context beyond the annotations: the MCP_API_KEY bearer requirement, a confirmation prompt before writing, and the crucial nuance that a retry on an existing site UPDATES name/category/tagline/description rather than being a no-op. 'Never deletes anything' largely restates destructiveHint=false, and no return shape is described, which keeps this short of a 5.

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

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

One dense paragraph, front-loaded with purpose before dependencies, then idempotency, then safety and auth. Every sentence contributes a distinct fact with no filler.

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

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

For a write tool with annotations, no output schema, and fully described parameters, this covers the remaining agent questions: auth, confirmation, retry behavior, and downstream dependencies. 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?

Schema coverage is 100%, so every parameter including the two enums is already documented in the schema. The description adds only the retry-update field list, while the url-as-identity semantics it implies are already spelled out in the schema's url 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 ('Start tracking one of your products') and immediately scopes it to the connected Sellular account. It further distinguishes itself from siblings by naming the four downstream tools that depend on tracking, so an agent can place it precisely in the workflow.

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

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

Gives an explicit trigger: 'Use when a product is missing from list_tracked_sites', naming the sibling whose output selects this tool. It also documents a precondition (the four account-scoped tools refuse to run on untracked products) that tells the agent when this must be called first.

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