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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds that it returns 'mention_count' and can filter by type, which is useful context. However, it does not discuss authentication requirements (api_key) or any rate limits. Since the annotations cover the safety profile and the description adds some but not rich behavioral detail, a 3 is appropriate.

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 somewhat long but well organized. It front-loads the purpose and usage guidance, then provides example queries, and finally lists arguments and return format. Each section serves a purpose; the example queries are especially helpful. While it could be tightened, it is not wasteful and remains readable, so a 4 is appropriate.

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 description covers the tool's purpose, usage examples, argument details, and return format. It also explains the relationship with news_get_entity. The only notable gap is the lack of mention of the api_key authentication parameter, but that is present in the schema. For a read-only search tool with a clear output format, the description is largely complete and an agent can call it correctly.

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 schema provides descriptions for all properties (query, type, limit, api_key), so the baseline is 3. The description adds value by listing the three main parameters (query, type, limit) with their purposes and default values, and by providing example queries that illustrate how to use them. It omits api_key, but that is covered in the schema. The concrete examples and the mention of default limit (20) go beyond the schema's basic descriptions, justifying a 4.

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 tool's function: 'Search across the current entity index: companies, people, products, and regions.' It specifies the verb (search), the resource (entity index), and the scope (four entity types). It also distinguishes itself from sibling tools by noting it is 'useful for discovery before using news_get_entity,' making it easy to tell apart from a general news search or a specific entity lookup.

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 provides explicit guidance on when to use the tool: 'Useful for discovery before using news_get_entity' and gives concrete example queries like 'is [company X] in the database?' It names one alternative (news_get_entity) but does not explicitly exclude other siblings such as news_search. It implies the use case but lacks a comprehensive when-not-to-use statement, so it earns a 4 rather than a 5.

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