analyze_feeds

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It thoroughly describes key behavioral traits: the statistical methodology (Beta-Binomial Bayesian model with empirical Bayes prior), caching behavior (1-hour cache, cost differences between first and subsequent calls), cost implications (Zone 1 requests based on parameters), and the effect of parameter choices (e.g., 'shrinks small-sample feeds toward the global mean'). This goes well beyond basic functionality.

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 appropriately sized and front-loaded, starting with the core purpose and methodology. Each sentence adds valuable information about the model, ranking options, caching, and costs. While dense with technical details, there is minimal redundancy, and the structure logically progresses from what the tool does to how it behaves.

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?

Given the complexity of the tool (statistical modeling, 7 parameters, cost implications) and the absence of both annotations and an output schema, the description does an excellent job covering behavioral aspects, methodology, and usage considerations. The main gap is the lack of information about return values (format, structure), which would be helpful since there's no output schema, but the description compensates well with other contextual details.

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 input schema has 100% description coverage, providing detailed documentation for all 7 parameters. The description adds some semantic context by explaining how 'prior_strength' affects shrinkage and how 'starred_pages' impacts data quality and cost, but most parameter meaning is already covered in the schema. This meets the baseline of 3 for high schema coverage.

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 explicitly states the tool's purpose: 'Analyze feed health and engagement using a Beta-Binomial Bayesian model.' It specifies the exact statistical method, the metrics computed (engagement_rate, credible_lower), and distinguishes it from siblings by focusing on analytical modeling rather than data retrieval or management operations like 'get_articles' or 'manage_subscription'.

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 clear context for when to use this tool: for analyzing feed engagement with Bayesian modeling, including caching behavior and cost implications. It mentions using 'credible_lower for conservative ranking' as an alternative sorting method, but does not explicitly state when not to use it or compare it directly to sibling tools like 'get_unread_counts' for simpler metrics.

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