kadal-store

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

Beyond readOnlyHint=true and openWorldHint=true, the description discloses that building the link charges nothing and buys nothing, that payment happens externally in the store's checkout, and that the agent must hand over the URL without asserting a purchase. This is exactly the side-effect context an agent needs before calling a "create_"-named tool.

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

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

The core purpose is front-loaded and every clause carries information (review page contents, payment location, when to use, no-charge semantics, URL handoff). The first sentence is a long run-on that is harder to parse than it needs to be.

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 correctly covers what the caller gets back (a URL to pass along) plus the crucial no-purchase constraint. It leaves required-item semantics and the item limit to the schema, which is acceptable but 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 description coverage, the schema already documents ref and the tier enum. The description adds only indirect meaning, hinting at licence choice via "see the licence", and says nothing about the undocumented slug field or the 20-item limit. Baseline-appropriate but not compensating 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?

The description states a concrete resource and outcome: a link to a store review page where the person reviews items (picture, licence, price), existing ownership and total, then pays in checkout. That clearly separates it from get_download_links (retrieving files) and search_products, though no sibling is named 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?

"Only when the person asked to buy or agreed to it" gives an explicit, actionable when-to-use condition, plus the caution against claiming a purchase was made. It stops short of naming alternatives (e.g. recommend or get_download_links for free items), so no exclusion routing is offered.

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 non-read-only, idempotent, non-destructive and open-world; the description makes the idempotency concrete via sha256 comparison and skip-if-present, and explains overwrite. It does not touch on auth/prerequisite requirements or which files are selected by default when nothing is narrowed.

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

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

The core action and its dedup semantics are front-loaded, and every clause (dir default, narrowing options, zip, return value) carries information. The middle sentence is dense with stacked options, which slightly hurts scannability but wastes no words.

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 write tool with a nested edition object and no output schema, the description covers return location ('where every file went'), defaults, filtering, and overwrite behavior. The main residual gap is the meaning of the required slug and any permission prerequisites.

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 86%, so the schema carries most parameter meaning; the baseline would be 3. The description adds provenance for fileIds ('from list_library'), restates the dir default relative to the project, and implicitly defines slug as the product selector, which the schema leaves 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 plus scope: download files the person owns into the project, with checksum verification and skip-if-identical behavior. It is clearly distinct from read-only siblings like list_library or get_product, though it never explicitly contrasts itself with get_download_links, which is the nearest 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?

Gives concrete narrowing paths: fileNames/fileIds (sourcing ids from list_library), an edition, or zip:true for the whole product, plus the overwrite condition. It stops short of stating when to prefer this over get_download_links or when not to use it at all.

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

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

Annotations only give readOnlyHint and openWorldHint, but the description adds genuinely load-bearing behavior: links expire in 10 minutes, each result carries name, size and sha256, and no cookie is required (curl -L works). The expiry window and auth-free access are exactly the operational facts an agent needs and cannot get from structured fields.

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

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

Three tight clauses separated by semicolons: what you get, how to narrow it, and where to go instead. The most decision-relevant fact (URLs, valid 10 minutes) is front-loaded and nothing is redundant with the schema.

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

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

With no output schema, the description carries the return-value burden itself and does so — listing name, size and sha256 plus the 10-minute validity. For a read-only link-generation tool with nested edition parameters, nothing needed to call it correctly is missing beyond the slug definition.

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 75%, so the baseline is 3, and the description earns an increment by clarifying that zip:true is additive ("adds one link") rather than replacing the per-file links. The gap is the required slug parameter, which has no schema description and no explanation in the description — the agent must infer it from siblings like get_product.

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

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

Opens with a precise verb+resource ("Download URLs for files the person owns") and immediately corrects a likely misconception — it returns URLs, not bytes. It also implicitly distinguishes itself from download_to_folder, which actually fetches files, so an agent can separate the two without opening either schema.

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

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

Explicitly routes the agent: "To put files into the project, download_to_folder does the download and the checksum for you" names the alternative and the condition that selects it. It also says how to narrow results (fileIds or an edition) and what zip:true adds, covering both when-to-use and how-to-scope.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds value beyond that by disclosing the shape and breadth of the response — including licence restrictions and update history — which is decision-relevant behavior, not just a restatement. Minor gap: no indication of payload size or whether very large products are truncated.

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, followed by a compact enumeration of returned facets and a one-clause caveat. The field list is long but justified in the absence of an output schema; no filler sentences.

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 return content and does so thoroughly, which is exactly what an agent needs to judge whether this tool supplies the licence and pricing data it wants. The only shortfall is the absence of any note on response size or failure behavior for unknown slugs.

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 with 100% schema description coverage, so the schema carries the documentation burden and a 3 is the baseline. The phrase 'one product' hints that the slug identifies a single record, but no format or resolution guidance (e.g., where to obtain the slug) is added.

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 ('Everything about one product') and then enumerates exactly which facets are returned — files, editions, prices per tier, pack membership, licence terms, update history. 'One product' also contrasts with the sibling search_products, so an agent knows this is a single-record fetch rather than a search.

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

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

Provides a concrete operational directive: 'Check the licence before suggesting a product for commercial work,' which tells the agent when the returned licence data must gate downstream recommendations. It does not explicitly route to siblings (e.g., search_products to find a slug first), so the selection guidance is context-clear but not exhaustive.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description earns credit by disclosing the actual contents of the result (tier, file fields, zip flag, latest update) in the absence of an output schema, though it says nothing about result size, pagination, or what happens for an empty library.

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

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

Two sentences, front-loaded with scope, and the parenthetical field list earns its space because no output schema exists. The follow-up routing sentence is short and actionable; nothing is padding.

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

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

With no output schema, the description carries the return-value burden and does so by naming the key fields. Minor gaps remain: no statement about result volume or whether the list is ever truncated, and no explicit tie-break against the other listing tools.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain; baseline 4 applies. The description correctly implies the call is argument-free by framing the result as everything the person owns.

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 scope statement ("Every product the person owns") and enumerates the payload: product card, tier, file metadata, zip availability, latest update. Clear verb+resource. It does not explicitly distinguish itself from search_products or list_shelves, which keeps it off 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?

Implies a workflow by saying "File ids go to download_to_folder or get_download_links," which tells the agent what to do after this call. It gives no guidance on when to prefer this over search_products or list_shelves, and no exclusions or prerequisites.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description does add useful behavioral context about the returned payload — per-note status, a plain status line, and the reply thread with Kadal — which matters because no output schema exists. It still omits scoping (own notes only?), pagination, and result volume, so it stops short of full disclosure.

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

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

A single front-loaded sentence with no filler. Slight ambiguity comes from internal jargon ('plain status line', 'Kadal's replies') that may not be self-explanatory, but nothing is redundant or bloated.

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 parameter descriptions, the description does well to sketch the returned fields. However, for a listing tool with filtering it should clarify filtering semantics and result scope/limits; the unexplained reference to 'Kadal' and the missing notion of whose notes these are leave real gaps.

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 0% for the single optional 'status' parameter, so the description must carry it. It merely re-lists the enum values in a phrase that reads as an output field ('with each one's status...') rather than explaining that status is an input filter, that it is optional, and what happens when it is omitted. This ambiguity risks the agent treating it as a return value instead of a filter.

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 resource as 'the person's notes (reports) on products' and enumerates part of its shape, so an agent can grasp what it deals with. But it never states the operation (list/retrieve) explicitly and does not distinguish it from the sibling report_problem, which also concerns problem reports. Purpose is inferable but not crisply differentiated.

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 guidance at all: nothing says to call this to review your own submitted reports rather than to search_products or report_problem. No exclusions, prerequisites, or alternative routing are given, leaving the agent to guess from the name alone.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description's real contribution is disclosing the returned fields (slug, name, blurb, product count, licence model), which matters since there is no output schema. It does not say whether all shelves are returned or whether results are paginated, which would matter for a catalogue-wide listing.

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

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

Two sentences, zero filler: the first defines the resource and its return shape, the second states the follow-up use. Front-loaded and appropriately sized for a simple zero-argument read tool.

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

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

For a trivial parameterless read call with no output schema, the description covers what comes back and how to use it, which is most of what an agent needs. The only real omission is result-set behaviour (completeness or pagination of the shelf list).

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a parameterless tool applies. The mention of shelf slugs is about downstream tools' inputs, not this tool's arguments, and is correctly framed that way.

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 the specific resource ('the store's shelves (its categories)') and enumerates what each entry contains: slug, name, blurb, product count, and licence model. The listing action is carried by the tool name rather than a verb in the description, but the resource is unmistakable and distinct from siblings like list_library or get_product.

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

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

Explicitly tells the agent what to do with the output: use a shelf slug to narrow search_products or recommend. That is clear workflow context tying this tool to two named siblings. It stops short of exclusions (e.g., when to prefer list_library or why one would browse shelves versus searching directly).

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

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

Annotations already establish readOnlyHint=true and openWorldHint=false, and the description reinforces this with "Reads nothing else and sends nothing anywhere", which is a useful explicit scope guarantee. It also discloses the extraction targets, which goes beyond the annotations. It does not cover edge cases such as large repos, ignored directories, or how a missing manifest is handled.

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

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

The purpose is front-loaded in the first clause, then the enumerated contents follow. The long parenthetical list of tool ecosystems is somewhat verbose but each item clarifies detection scope. The final sentence about the `text` field is well placed as a call to action.

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 single-parameter read tool with annotations and no output schema, the description carries the necessary load: it explains what is collected and that the response exposes a `text` field for downstream use. Only marginal gaps remain, such as response size or behavior on non-project directories.

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 `dir` parameter is documented in the schema as a folder relative to the project with a default. The description never mentions `dir` or its relative-path semantics, so it adds nothing beyond the schema. Baseline 3 applies when the schema does the documentation 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 names a specific verb and resource (summarise a project folder) and then enumerates exactly what the summary contains: package.json/pyproject.toml/Cargo.toml metadata, dependency names, detected tools, README headings, file-type counts, top-level names. It also distinguishes scope explicitly ("without its contents"), so an agent knows this is metadata extraction, not file reading.

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 made concrete by tying it to a workflow: it is what `kadal-store recommend --from` sends, and its `text` should be passed to recommend as context. That tells the agent when to reach for it. It stops short of naming exclusions (e.g. when to call `list_my_notes` or `search_products` instead), so it is clear but not fully comparative.

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

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

Annotations already declare readOnlyHint and openWorldHint, so safety is covered. The description does add genuine behavioral context: the result is a shortlist, each item carries a one-line `why` and a score, and packs are surfaced via `ownedOf`. It does not mention ranking quality, latency, or whether prices/availability are live, but for a read-only recommendation call that is a reasonable level of disclosure.

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

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

Dense but front-loaded: the purpose lands in sentence one, then the input constraints, then the result shape, then the follow-up flow. The phrase 'then recommend with your own reasons' inside the recommend tool's own description is slightly circular and could be tightened, but no sentence is filler.

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

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

With six parameters, no output schema and only read-only annotations, the description carries the burden well by describing the return payload (why, score, packs, ownedOf) and the shortlist limitation. The remaining gaps are minor: no pagination or truncation behavior for `limit`, and no signal about ranking confidence.

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

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

Schema coverage is 100%, so the baseline is 3, and the description earns an extra point by telling the agent what to put in `context` (plain lines about the project plus the person's request) and what must never go in it (file contents, secrets, personal data). It also implicitly connects `includeOwned`/`packs`/`ownedOf`, which the schema alone does not tie together.

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?

'Products that fit what the person is working on' states the resource and the matching basis clearly, and the closing 'this only shortlists' scopes the output. It is distinguishable from search_products by being context-driven rather than query-driven, though it never names the sibling directly.

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 prescribes a concrete workflow: feed in project_summary's `text` plus the person's request, then read get_product for the best few and present with your own reasons. What is missing is an explicit negative rule (when to prefer search_products or list_shelves instead), so it falls short of full when/when-not coverage.

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

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

Beyond the annotations (which confirm it is a writable operation), the description offers critical workflow context by stating that the notes are 'private to the person and Kadal' and how replies are handled. This provides necessary meta-information regarding the note's visibility.

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?

While the description is moderately sized, it is highly dense and functional. It front-loads the purpose and flows logically into behavioral constraints, ensuring that almost every sentence provides necessary instructional value.

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

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

The tool handles complexity by managing three different issue kinds and multiple media formats. The description comprehensively covers the boundaries of reporting (what to check, how to report it) and the privacy implications of the resulting note.

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?

Given that schema coverage is moderate (67%), the description is excellent at providing semantic guidance for the media location parameters. It explicitly links `page` to PDFs and `timeSeconds` to audio/video, allowing the AI to logically group and select the correct parameter based on the file type.

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 defines the action (reporting) and the specific types of issues (mistake, question, or idea) it addresses regarding a product. By focusing on these specific problem types, it strongly differentiates itself from general library searching or listing siblings.

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 provides explicit behavioral rules for usage, such as reporting 'only what you checked' and filing it 'once per problem.' This minimizes ambiguity and sets clear constraints on how and when the tool should be invoked.

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 and openWorld, so safety is covered. The description adds valuable behavioral context beyond that: exactly what a product card contains, that prices are in US cents per licence tier, that `owned` reflects the caller's existing tier, and that results are cursor-paginated via nextCursor. It does not describe ranking behavior or empty-result behavior, but it is substantially more informative than the annotations alone.

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 compact sentences, front-loaded with purpose and then the return shape. Every clause carries useful information about fields, pricing units, ownership, and pagination; there is 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 10-parameter search tool with no output schema, the description does a good job specifying the return shape, price units, ownership semantics, and pagination. It could say more about result ordering and how multiple filters interact, but an agent has enough to call and interpret the tool correctly.

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

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

Schema description coverage is 90%, so the schema already explains most parameters, including examples for query, shelf, style, and format. The description reinforces pagination via nextCursor and clarifies that `owned` is a returned field rather than an input, but adds little parameter meaning beyond what is already documented.

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 ('Search the catalogue') and immediately describes the returned product cards, making the operation unambiguous. It does not explicitly contrast itself with siblings like get_product or list_shelves, which keeps it short of a 5, but the search framing is distinct enough for an 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?

Usage is implied: this is the tool for finding products by query or filters. However, there is no explicit guidance on when to prefer list_shelves, get_product, or recommend, nor on how filters combine. The schema hint that shelf slugs come from list_shelves helps, but the description itself does not route the agent among alternatives.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds substantive context by disclosing what the call returns (identity fields, scopes, owner flag), which matters because no output schema exists. It does not say what happens when nobody is signed in, whether that yields an error or an empty result, which is the main remaining 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?

Two sentences, both earning their place: the first lists the return content, the second gives the usage condition. The payload is front-loaded 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 zero-parameter read tool with no output schema, the description covers the essentials: what is returned and when to call it. The only missing piece is unauthenticated or error behavior, a minor gap given the tool's simplicity and its read-only annotation.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, and nothing about parameters 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?

The description states a specific resource (the signed-in person) and names the fields returned: id, name, email, scopes, and store-owner status. It is clearly distinct from every sibling tool, which handle shelves, products, notes, and downloads. It stops short of a leading verb, but the intent is 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?

The description gives an explicit trigger: 'Call it when unsure whether the person is signed in.' No alternatives are named, and none of the siblings appear to overlap with an identity check, so there is no meaningful exclusion to state.

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