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

Annotations already declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description goes further with real behavioral context: exact total returned, default/max page size, sort default, cross-team access returning not-found, and person runs lacking a relevance score and never ordered by one. It omits whether results are cached or how fresh they are, but this is well above the annotation baseline.

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 purpose and the feed/run_id split are front-loaded before any caveats, and most clauses carry information. The second and third sentences are long and dash-heavy, bundling return-shape, error behavior, and person-data gating into single sprawling sentences, which costs a little readability.

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 carries the full burden and does so: it names the row fields (headline, category, verification state, corroborating source count, run_id, team_id, team_name), the paging contract, the sort options, and the special case for natural-person runs. An agent has enough to call it correctly and interpret the response.

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 100%, including the sort enum values, limit bounds, offset, and the note that run_id causes the other arguments to be ignored. The description largely restates this (default 25, maximum 100, sort recent/score) rather than adding syntax or format meaning, so the baseline 3 applies despite the added detail on row-level fields like run_id and team_id/team_name.

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 opening states a specific resource ('dated, cited developments surfaced by your team's research runs') with a clear noun phrase, and it immediately distinguishes the two modes (feed vs. single-run load) that a sibling tool would otherwise have to cover. An agent can tell what this returns and how it differs from search_stonewake_docs or company_news without opening the schema.

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 explicitly states when each mode applies: omit run_id for a paged feed, pass run_id to load that whole research run. It also names the failure condition (another team's run_id returns not found, like an unknown one) and the gating condition for person-related runs. There is no reliance on inference.

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