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

Annotations already declare readOnly/ idempotent/ non-destructive/ closed-world, so the safety profile is covered. The description adds real value beyond them: only non-default settings are emitted, the snippet is minimal by design, and it enumerates the two failure modes (AgentNotFoundError for a missing or foreign agent, AgentValidationError for a missing public URI).

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?

Front-loaded with the core action, then organized into snippet behavior and a Raises block. Every sentence carries information, though the prose is slightly more expansive than needed for a tool this simple.

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 7 params, one required, 100% schema coverage, rich annotations and an output schema, the description covers the remaining gaps well: the public-URI precondition, the output's minimality, and the error cases. A cross-reference to gnosari_check_uri is the only notable omission.

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% with enums and defaults documented for all 7 parameters, so the schema carries the semantics. The description only adds the meta-rule that defaults are suppressed in the output, which is not per-parameter detail; baseline 3 applies.

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 a specific verb+resource: 'Generate an HTML embed snippet for the Gnosari chat widget,' and the body clarifies it returns a ready-to-paste snippet. This is clearly distinguishable from setup siblings like gnosari_manage_appearance, which configures the widget rather than emitting embed code.

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?

Provides a concrete precondition ('the Gnosari must have a public URI before it can be embedded') and states where the output goes ('paste it right before the closing </body> tag of every page'). It does not, however, point at the obvious sibling gnosari_check_uri as the way to verify that precondition.

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