Search

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

Beyond the read-only, idempotent annotations, it discloses the important language limitation that English names usually return nothing. It also provides partial result behavior by explaining that `entities` contain team IDs of kind Team, though other result types are not described.

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 definition is compact and front-loads its purpose and ID-resolution role. Every subsequent clause earns its place by specifying the first-use workflow, downstream consumers, or the Persian-language constraint.

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 simple two-parameter search tool, the schema, annotations, and description collectively provide enough information to select and invoke it correctly. With no output schema, however, the player workflow is less complete than the team workflow: it does not identify the player entity kind or connect it to v3_player, and news/video result handling is likewise unspecified.

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 already 100%, including the Persian query requirement and the per-kind result limit. The description adds practical query semantics by warning that English names usually find nothing, rather than merely restating the schema.

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 gives a specific verb, resource, and scope: searching Varzesh3 for teams, people, leagues, news, and videos by name. It also distinguishes the tool as the name-to-ID resolver feeding sibling tools such as v3_team and v3_team_matches.

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 explicitly says to use the tool first when the user names a team or player and identifies the downstream tools that consume a Team entity's ID. The Persian-search warning further guides how to formulate a successful request.

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