list_news

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

No annotations are provided, so the description fully bears the burden of transparency. It discloses key behavioral traits: the limit cap (OPENPROJECT_MAX_PAGE_SIZE), the meaning of 'total' (only page count, not all matches), the early termination of search, and the explicit pagination mechanism via next_offset. These are non-obvious and crucial for correct usage, going beyond typical descriptions.

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 concise and well-structured: first sentence states the primary purpose, followed by a detailed paragraph on pagination and total semantics. No redundant wording; every sentence adds value. The information is front-loaded and the technical details are organized logically.

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?

The tool involves pagination and subtle total behavior, which the description explains thoroughly. It does not describe the structure of returned news entries, but no output schema exists, so it might be inferred or expected. It also does not mention permissions or side effects, but as a list tool (read-only) this is likely not necessary. Overall, it is complete for the core usage, with minor gaps in return structure and explicit authorization requirements.

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 0%, so the description must compensate. It explains the 'filtered by project or title/summary search' which maps to 'project' and 'search' parameters, and details limit and offset semantics including the cap and offset progression. It adds meaning beyond the schema by clarifying the limit's cap and the offset's role in pagination, though it doesn't elaborate on search syntax or project format.

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 clearly states that it lists news entries with optional filters for project and search (title/summary). It uses a specific verb 'List' and resource 'news entries', distinguishing it from sibling tools like get_news (single entry) and list_boards (different resource). It is unambiguous and provides the essential purpose.

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 gives clear context on when to use the tool: for listing news with optional filtering. It implicitly differentiates from get_news by focusing on list functionality. However, it does not explicitly mention alternatives or when not to use it (e.g., if you need a single news entry, use get_news). The pagination guidance is useful and gives usage direction, but lacks explicit exclusionary language.

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