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

Annotations already cover readOnly/idempotent/non-destructive/reduced-open-world, but the description makes the safety profile concrete: 'never claims, publishes or charges.' It also discloses input-dependent behavior (with SoundCloud it runs an exact match and returns claim/create guidance). Adds real value beyond the annotation flags, though no rate/permission details.

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-loads the trigger ('Use this when...') and stays within three sentences. The middle sentence is a dense run-on enumerating return contents, but no sentence is wasted and the key scoping constraint is stated up front.

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?

For a no-required-param onboarding tool with no output schema, the description usefully enumerates what comes back (claim/create guidance, published page examples, benefits, pricing/signup/billing links) and the safety guarantees. Complete enough to invoke correctly, though the audience enum values are not explained.

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 75%, so much is documented already, but the description adds semantic behavior: SoundCloud triggers an exact database lookup and claim/create guidance, while name returns candidates to confirm. The audience enum and city parameter are left to the schema, which is acceptable at this coverage level.

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 purpose: optional Dizko setup for event discovery or for DJs/artists/venues/etc., and what it returns (claim/create guidance, page examples, benefits, pricing links). It implicitly separates itself from discovery tools by noting it should not interrupt event searches, though no sibling is named directly. Clear but slightly cluttered by the long enumeration of audiences.

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 when to use it ('Use once at setup or when the user asks about their own page') and when not to ('do not interrupt event searches'). This is a genuine when/when-not pair that routes the agent away from the search/recommend siblings.

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