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

Goes far beyond the readOnly/idempotent annotations by detailing accent/apostrophe normalization, per-hit matched_fields and score, the token-weight formula (name 3, tags 2, content 1), and the centrality bonus up to 0.9. It even explains why scores can differ despite identical matched_fields, which prevents misinterpretation.

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 dense but each sentence adds critical information: scope, normalization, result shape, scoring weights, the meaning of the centrality decimal, and usage routing. It front-loads the core search action and keeps the explanation structured from behavior to interpretation.

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?

Covers the tool's full behavioral contract: what it searches, how matching and scoring work, how to interpret ambiguous scores, and when to call it relative to get_entity. Output schema covers return values, and annotations cover safety/idempotency, so nothing necessary is missing.

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 100%, so the baseline is 3. The description reinforces the schema's 'user's own words' guidance and adds context about how query tokens are weighted, but it doesn't add new parameter-level information beyond what the input schema already provides.

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 'Full-text search over the knowledge graph' with the specific verb 'search' and the resource 'knowledge graph'. The description also distinguishes it from sibling get_entity by framing search as the entry point for questions rather than IDs.

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?

Explicitly says 'Use this whenever you have a question rather than an id, then follow up with get_entity', giving both a positive trigger and an exclusion (when you have an id). It names get_entity as the follow-up alternative, providing clear routing guidance.

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