Oakferry Agents

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false and destructiveHint=false, so the safety and repeatability profile is fully covered elsewhere. The description adds one genuinely useful behavioral detail, that each row is sourced (provenance per row), but says nothing about table size, pagination or ordering.

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, no filler. The output/what-it-is statement is front-loaded and the parameter routing follows immediately, with each clause doing distinct work.

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-optional-parameter, read-only lookup tool with no output schema, the description covers what is returned at a high level (tables, sourced rows) and all three call patterns. Only minor gaps remain, such as pagination or result ordering, which are unlikely to block 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 coverage is only 50% and product_id has no schema description at all, so the description must carry weight — and it does, explaining that product_id returns every table the product appears in and that omitting both params lists tables. It adds the inverse-lookup semantic that the bare schema cannot convey.

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

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

States a concrete resource and shape: comparison tables of products and their alternatives on shared attributes, with each row sourced. That clearly separates it from get_product, list_attributes and search_products without needing to open a schema, though it never names those siblings 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?

The second sentence gives explicit selection logic across all three invocation modes (id for one table, product_id for every table containing that product, nothing to list), which is exactly the routing an agent needs. It stops short of stating when not to use this tool versus a sibling like search_products.

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/non-openWorld, so the safety profile is covered. The description adds real behavioral value by disclosing the return content, notably 'when not to recommend it' and 'third-party coverage and sources', which tells the agent this is a decision-support payload, not just a record fetch. It doesn't cover absence/error behavior, keeping 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?

A single front-loaded sentence that names the resource first and then enumerates contents; each item earns its place as a signal of what the payload contains. The colon-list is dense but not padded.

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

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

With no output schema, the description must carry return-value meaning and it largely does by listing the data categories returned. Gaps remain around response format, sourcing of 'third-party coverage', and failure behavior for an unknown id.

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?

One parameter at 100% schema coverage, and the schema already documents 'Product id from search_products'. The description adds no parameter-level detail (id format, casing, validation) so the baseline 3 for fully-covered schemas applies.

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

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

States a specific verb+resource ('full facts for one product') and enumerates exactly what is covered: prices, ratings with dates, features, attributes, negative-recommendation signals, coverage and sources. The singular 'one product' implicitly contrasts with search_products/compare_products, but no sibling is named, so it stops short of a 5.

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

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

The description never says when to use this versus list_attributes, search_products or compare_products, nor when not to use it. The only routing hint ('Product id from search_products') lives in the schema, not the description, leaving the agent to infer the search-then-fetch workflow.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds the return contract: keys, the values used per key, and how many products set each. It does not note whether value lists are truncated or capped, which is the main remaining behavioral question for an inventory-style 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 with no filler; the resource and its contents come first, and the cross-reference to search_products is placed last as actionable guidance.

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 parameters, the description carries the return-shape burden and does so reasonably, tying the output to its use in search_products. Minor gap: no mention of result size, pagination, or value-list truncation.

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?

Zero parameters, so the schema baseline is 4 and there is no parameter meaning for the description to add. No penalty for a parameterless discovery tool.

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 resource (filterable attribute keys) and enriches it with what comes back: each key's values and product counts. It is clearly distinct from siblings like get_product and compare_products, though it never states a verb 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?

It gives a concrete downstream use: 'Use these keys in search_products attributes,' which tells the agent this is the discovery/feeder tool for filtering. No when-not or comparison against get_product/compare_products is offered, so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds useful return-format context ("Each result says why it matched"), which goes beyond what the annotations provide.

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

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

Three tightly written sentences, front-loaded with the core purpose, followed by parameter-allocation guidance and a cross-reference. No filler; every sentence earns its place.

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

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

For an 8-parameter, nested-object, no-output-schema search tool, the description covers how to route inputs and vaguely what results contain. It could say more about the result payload (e.g., pagination or fields), but it is adequate 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 coverage is 75%, so the schema already documents most parameters. The description adds genuine semantic value by partitioning parameters into hard-requirement filters (platform, max_price, free, no_subscription, attributes) versus free-text query, guiding allocation between them beyond the schema text.

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 ("Find products") with scope ("matching a person's constraints"). It distinguishes itself from list_attributes by routing there for filterable keys, but does not differentiate from compare_products or get_product, so it falls short of a full 5.

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

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

Gives clear operative guidance: put hard requirements in the filters and the rest in query, and call list_attributes to discover filterable keys. It lacks explicit when-not-to-use guidance relative to compare_products/get_product, so it stops short of 5.

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