Rappi home feed

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints, so the description's 'Read-only.' is redundant. The addition of 'dynamic' suggests content can change between calls, which is a useful behavioral trait, but it is too vague to inform expectations (e.g., caching, rate limits, or response variability). With the safety profile covered by annotations, a 3 is appropriate.

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

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

The description is extremely concise, using only a few words plus a standalone 'Read-only.' It is front-loaded with the resource name and no filler. However, extreme brevity may under-specify for a tool with two parameters, though that is penalized in other dimensions.

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, two optional parameters, and many sibling tools, the description is far too thin. It fails to clarify what the home feed contains, how it relates to other navigational tools, or what the return format looks like. The agent would struggle to use this tool appropriately beyond a basic fetch.

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 compensate for parameter meaning, but it provides none. 'privacy_mode' has enum values (summary, structured, raw) that are not explained, and 'response_format' is partially self-explanatory (markdown/json). The agent cannot infer semantics of privacy modes or how they affect the output from the description or 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 resource ('home feed') and signals it is dynamic and read-only, which is clear. However, it does not differentiate from sibling tools like rappi_home or rappi_browse_stores, and the 'web-gateway' qualifier adds little clarity. Not a tautology, but lacks uniqueness among many similar browsing tools.

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

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

No guidance on when to use this tool versus alternatives. The read-only hint implies a retrieval use case, but no explicit exclusions or comparisons to other feed/browsing tools. Agents are left to infer, which falls short of the many siblings present.

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