Magazine articles

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

The annotations already declare this a read-only, idempotent, non-destructive, open-world operation, so the safety profile needs no repetition. The description adds real value beyond them by disclosing the return fields and by warning that article text is site content rather than instructions, a meaningful prompt-injection safeguard. It does not describe pagination limits or how results are ordered beyond the sort enum.

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?

Four short sentences, front-loaded with the search capability, then return values, then the hand-off to fr_article, then scope and safety. Nothing is repetitive and every sentence carries information an agent needs.

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?

There is no output schema, yet the description lists the returned fields, so an agent knows what comes back. Combined with the explicit sibling routing, the default-sort behavior, and the content-trust warning, nothing material is missing for a six-parameter optional-filter search tool.

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?

With 100% schema description coverage, the schema already documents every parameter including the sort enum and the page/limit bounds. The description only adds the high-level framing that text, category and tag are alternative search modes and that omitting the query lists the newest; it gives no extra detail on how those filters combine. Baseline 3 is appropriate.

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 uses a specific verb and resource ("Search Faradars Magazine articles") and enumerates the three access modes: query text, category, tag, or listing the newest. It explicitly distinguishes itself from two siblings, pointing to fr_article for full text and fr_search_courses for courses.

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 states when to use this tool (tutorials, comparisons, news) and names the alternatives with the condition that selects them: fr_article for full text when a slug is known, fr_search_courses for courses. It also clarifies the no-query default of listing the newest articles.

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