tasarim.ai AI Catalog

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is low; the description goes further by bounding the output contract ("Distinguishes catalog-record values from verified field evidence and unknowns") and explicitly disclaiming synthesis ("no invented scores, winner, pricing, or benchmarks"). This meaningfully sets expectations the annotations cannot, though it doesn't say whether unknowns appear per-cell or are omitted.

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 short sentences, front-loaded with the core action and scope, then the output contract, then the prerequisite. Slightly dense jargon ("stored claim scopes") but 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?

With an output schema present, the description needn't describe return values, and the annotations cover safety; what remains necessary — cardinality, id provenance, and the no-synthesis guarantee — is all present. The unmentioned locale parameter is the one loose end.

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 0%, so the description must carry parameter meaning. It does explain the origin and purpose of kind/slug and restates the 2-4 cardinality, but the locale parameter — the only other input, with an 8-value enum — is never mentioned in the description, leaving a gap the schema only partially fills.

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: "Compare two to four published catalog products using the same criteria." It signals the upstream relationship ("kind and slug returned by discovery") which implicitly separates it from discover_ai_products, but it never names get_ai_product_evidence or explains how comparing multiple products differs from fetching one product's evidence.

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 kind and slug returned by discovery" is an explicit prerequisite that tells the agent what it must do before calling, and the min-2/max-4 constraint is clear. There is no explicit when-not clause or named alternative, so the agent must infer that alternative from the sibling list.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely new behavior: what is withheld (raw unverified descriptions, provider commerce/tracking URLs), what is surfaced (claim scopes, recorded limitations, explicit unknowns, language fallback), and that links may carry a visit marker. It stops short of describing result ordering or what an empty query returns, so it is strong but not exhaustive.

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 dense sentences, front-loaded with the purpose and followed by return/withholding semantics and the scope boundary. No filler, though terms like "claim scopes" and "fixed visit marker" are opaque enough to cost some clarity per token.

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?

An output schema exists, so return structure need not be explained, and annotations cover the safety profile; the description fills the remaining gaps by stating the non-web, non-generative boundary, the withholding policy, and language fallback. For a zero-required-parameter search tool this is 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?

Schema description coverage is 0%, so the description must carry the load. It adds meaning for query (short names, not prose), the task filters (supportsTask/freeCompletionForTask require stored field evidence) and locale (language fallback), but says nothing about kind, limit, access, or openSource, leaving a substantial share of the nested schema unexplained.

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 ("Search tasarim.ai's published catalog") and scopes the input style (product names, categories, needs). It implicitly separates itself from siblings by declaring the catalog is bounded and non-generative, but never names compare_ai_products or get_ai_product_evidence, so the differentiation is inferred rather than stated.

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?

"Concise product names, categories or needs" gives real query-shaping guidance, and "verified task filters require stored field evidence" tells the agent task filters are strict. However, there is no explicit when-to-use-this vs when-to-call-compare-or-get-evidence guidance, so routing between the three siblings is left to inference.

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

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

Annotations already declare a safe, idempotent, closed-world read, yet the description still adds substantial non-obvious behavior: catalog profiles are labeled as catalog records rather than independent evidence, provider/commerce/tracking URLs are withheld with reasons, a fixed visit marker may be attached, and source dates are not re-verification. It also states what is excluded (unpublished drafts, internal review metadata), which is exactly the disclosure an agent could not get from structured fields.

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

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

Front-loads what is returned, then stacks caveats in short declarative clauses with no filler. Some phrasing is compressed to the point of opacity ('provider/evidence commerce/tracking URLs'), which costs a bit of clarity for the brevity gained.

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

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

Covers return contents, exclusions, URL withholding, and date semantics, and an output schema exists so return shapes need not be spelled out. The only real hole for a nested-object, enum-bearing tool is the unexplained locale parameter and its default behavior.

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

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

Schema description coverage is 0%, so the description is the only source of parameter meaning. It partially compensates by explaining where 'kind' and 'slug' come from (discovery output), but the 'locale' parameter and its enum of eight values go entirely unaddressed in both schema and description.

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

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

Opens with a specific verb and enumerated resources: 'Retrieve stored field claims, source provenance and recorded limitations for one AI product.' The phrase 'for one AI product' implicitly contrasts with compare_ai_products, but neither sibling is named, so an agent must infer the boundary.

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 kind and slug returned by discovery' gives an input-sourcing hint that implies the discover_ai_products prerequisite, but there is no explicit statement of when to choose this over compare_ai_products, or of any precondition beyond argument provenance.

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