search_articlesSearch this publication's articles by keyword. Returns the best-matching titles, dates, canonical URLs, and short summaries.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results (default 5, max 20) | |
| query | Yes | Search keywords |
| Name | Required | Description | Default |
|---|---|---|---|
| total | No | ||
| articles | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds useful behavioral context by mentioning 'best-matching' results and the returned fields, but it does not disclose pagination, sorting details, or edge cases. This is reasonable given the output schema exists.
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 two tight sentences with the action front-loaded. Every phrase adds either scope or return-value context, and there is no filler or repetition of the annotations.
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 low-complexity, read-only search tool with full parameter documentation and an output schema, this description is largely sufficient for an agent to call it correctly. The only meaningful gap is disambiguation from the similarly named 'search' sibling, which is more of a usage-guideline concern.
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 provides full descriptions for both parameters: 'query' is 'Search keywords' and 'limit' has default/max constraints, so schema coverage is 100%. The description adds no meaningful parameter-level information beyond restating the keyword-search action.
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 the action ('Search'), resource ('this publication's articles'), and approach ('by keyword'), so it is easy to distinguish from list/fetch/get siblings. However, it does not explicitly differentiate itself from the similarly named sibling 'search', leaving a small ambiguity.
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 implies the tool is for keyword-based article search within this publication, giving a clear basic context. It does not state when to prefer this tool over 'search' or other alternatives, and no exclusions or routing guidance are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
`search` and `search_articles` both perform keyword search and overlap for article content, while `fetch` and `get_article` both retrieve full text via different identifiers. `list_recent_articles` and `popular_content` are more distinct, but the overall surface has several boundary cases that could mislead an agent.
Names mix bare verbs (`fetch`, `search`), verb-noun forms (`get_article`, `list_recent_articles`, `search_articles`), and a noun phrase (`popular_content`). There is no consistent convention across the set, though the verbs used are generally understandable.
Six tools is within a reasonable range for a content gateway, and each area—search, retrieval, recent, popular—is represented. However, the duplicate search and fetch functionality means the set could be trimmed to four tools without losing much capability.
The server covers the main content-consumption workflow: discover via search/recent/popular, then retrieve full text. There are minor gaps (e.g., no explicit article-by-ID endpoint other than `fetch`, no listing beyond recent/popular), but agents can usually work around them.