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

Beyond the readOnly/idempotent/destructive annotations, the description reveals how matching normalizes accents and apostrophes, the exact token weights per field, and the centrality bonus mechanics. It even warns that the decimal represents inbound edges, not text relevance, which prevents misinterpretation of scores.

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 front-loaded with the core purpose, then efficiently layers normalization, scoring, and usage guidance. Every sentence contributes distinct information, and the whole thing remains compact enough for quick reading.

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?

Given the output schema and annotations covering safety, the description fully covers what the agent needs: when to use it, how matching works, how scores are computed, and what the follow-up should be. Nothing essential is missing for a search tool of this complexity.

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 the schema already documents query and limit. The description mostly repeats the normalization behavior from the query parameter and adds scoring context, but it does not introduce new parameter meaning beyond what the schema provides. 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 opens with a precise verb and resource: 'Full-text search over the knowledge graph.' It also distinguishes itself from siblings by stating this is for questions rather than IDs and explicitly names get_entity as the follow-up tool, so an agent can select it correctly.

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?

'Use this whenever you have a question rather than an id, then follow up with get_entity' provides a clear decision rule and names an alternative. This is explicit enough for an agent to know when search is appropriate versus when an entity lookup is needed.

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