find_my_ratings

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

Annotations already declare read-only, idempotent, non-destructive, open-world behavior, so the safety profile needs no restating. The description's genuine addition is that filters are AND-combined rather than OR'd, plus the 1-10 rating bound and date format. It does not say what limit=100 means for completeness, whether results are truncated, or how totals are reported, which matters for a 14-filter search over a whole history.

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 a single purpose sentence, then compactly enumerated arguments in the same order an agent will fill them. No filler prose; the length is justified by 14 undocumented parameters. The example phrases cost a little space but earn it by demonstrating filter composition.

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 14-parameter, zero-schema-coverage search tool, the description covers purpose, filter composition, and per-parameter meaning, and the output schema handles return shape. What's missing is the relationship to the sibling my_ratings/my_rating_for and any statement about result pagination or caps.

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 carries the full burden — and it discharges most of it, glossing all 14 parameters with useful specifics (rating 1-10, revised YYYY-MM-DD date format, sort keys enumerated, title_type examples). Gaps remain: the query matching semantics (substring vs fuzzy), whether genre is exact-match, and how year coexists with year_from/year_to are unstated.

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: "Search the configured user's whole ratings history." The agent knows exactly whose data and what domain. It stops short of naming the near-identical sibling my_ratings or my_rating_for, so differentiation must be inferred from the name alone.

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 line "Every filter is optional and they combine" plus three natural-language examples conveys how filters compose, which is real usage guidance. However, nothing says when to prefer this over my_ratings, my_rating_stats, or advanced_title_search, and no exclusions are stated.

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