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

With readOnlyHint/idempotentHint already supplied by annotations, the description still adds real behavioral context: restricted sources return articles without full text, and the archive requires the Pro or Scale plan. That is exactly the kind of caveat an agent needs before promising full-text results, though response shape is left to the output schema.

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 core action and followed by narrowing, paging, and two caveats. Every sentence carries information; the only mild redundancy is repeating the semantic/keyword distinction already in the schema.

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 an 8-parameter search tool with an output schema, the description covers what to search, how to narrow, how to paginate, default recency, the plan gate, and the restricted-source caveat. Complete enough to call correctly; only the sibling-routing guidance is absent.

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%, so every parameter including mode, since, cursor, goal_id, portal_id and include_expired is already documented. The description only restates the mode distinction and the cursor paging convention, adding little beyond the structured fields, so the baseline 3 applies.

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?

States a specific verb (searches) and resource (news articles in the user's account) and distinguishes two matching modes, semantic vs. keyword title words. It does not differentiate itself from siblings like semantichub_search_brain or semantichub_api_search, so it stops short of a 5.

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?

Gives useful context about defaults: only current articles are searched unless include_expired is set, and paging is done via next_cursor. However it never says when to prefer this tool over semantichub_search_brain or semantichub_api_search, leaving the agent to infer the boundary.

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