suggest_relations

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

No annotations are supplied, so the description carries the full burden. It does useful work by declaring the tool is advisory ('只作建议'), implying no ontology mutation, and by disclosing the three heuristics that generate suggestions. However it says nothing about what a suggestion record contains, whether results are ranked or deduplicated, or how a saved run must be in a particular state — real gaps for an unannotated tool.

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?

One front-loaded sentence that first states the purpose and the suggestion-only constraint, then enumerates the three patterns. No filler or repetition. Slightly dense — the colon-separated clause list is readable but could be broken into bullets for faster scanning.

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?

With no annotations and no output schema, the description must cover both behavior and return shape. It handles the behavior side reasonably (advisory nature, detection rules) but never describes what the agent receives back — e.g. candidate relation tuples, confidence, or the identifiers needed to act on a suggestion. That is a meaningful omission for a discovery tool that feeds a confirmation step.

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% and the single parameter saved_as already documents that the value comes from list_runs or build_ontology. The description adds no parameter-level meaning beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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 states a specific verb+resource (suggest relations) and scopes it precisely as 'relations visible in the data but absent from the ontology'. It further enumerates three concrete detection patterns (unconnected objects on the same row, a column holding another object's name, a column pointing by name/value to another object's ID), which makes the purpose unmistakable. It does not explicitly name list_relations as the contrasting tool, 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?

Usage is only implied: 'suggestions only' tells the agent this is a non-committal discovery step, and the natural downstream step (confirm_derived / confirm_ontology) is never named. There is no explicit statement of when to call this instead of list_relations, nor any prerequisite or exclusion. Adequate for inference, but guidance is left to the agent.

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