set_synonym_state

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

With no annotations, the description carries the full behavioral burden. It explains the meaning of State values (e.g., 'Deleted to suppress an auto-generated term'), the optional Weight range, and the objectType/table requirements. However, it does not specify whether setting synonyms replaces or appends to existing ones, a meaningful behavioral detail.

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?

Three concise sentences cover purpose, key parameters, and a critical limitation. No fluff; every sentence earns its place. The structure is front-loaded with the core purpose and then expands with usage and scope notes.

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 addresses the tool's purpose, parameter semantics, key state meanings, and the scope limitation (flat per-entity terms only). It does not mention return values, but there is no output schema, and the absence is typical. Given the 8-parameter schema with high coverage, this is adequate but could note whether the operation overwrites existing synonyms.

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 covers 88% of parameters, so baseline is 3. The description adds value by clarifying semantic intent: State values are explained ('Authored to make terms stick', 'Deleted to suppress'), Weight is specified as 0..1, and objectType values are enumerated. It also clarifies the table parameter's conditional need beyond the schema's label.

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 authors Q&A synonyms with an explicit State and optional Weight. It identifies the resource (Q&A synonyms) and distinguishes itself from sibling tool set_synonyms by noting it extends functionality with State/Weight support.

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 explicitly references set_synonyms ('which only adds bare terms') as an alternative, implying when to use this tool (when State/Weight needed vs bare terms). It also provides usage nuances like passing the object's table for column/measure/hierarchy and notes the schema limitation to flat per-entity terms.

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