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

Annotations only declare destructiveHint/readOnlyHint/idempotent flags; the description goes well beyond them by disclosing the quota-cap 403 behavior, that delete cannot be undone, that a signal only notifies and never trades, the 403 asymmetry for Scan/agent-owned signals, and the defaults for delivery_channels (telegram) and edge_triggered (true). That is meaningful operational context an annotation cannot express.

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 verb and the ownership constraint, and every clause carries information. It is, however, a single dense paragraph mixing per-action requirements, defaults and error cases, which makes it harder to scan for a specific action than a short bulleted split would be.

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 12-parameter, nested-object, mutation-heavy tool with no output schema and near-zero schema descriptions, the description supplies everything needed to call it correctly: prerequisites, per-action requirements, predicate syntax, defaults, and failure modes. No output-schema gap exists, so nothing material is missing.

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?

With schema coverage at just 8%, the description carries the full burden and does: interval_minutes range and hour-multiples rule, query vs queries (up to 8, each with a label), the predicate grammar with the full operator list and AND/OR nesting form, cron_id required for non-create actions, and a concrete worked example. Nearly every one of the 12 parameters gains meaning beyond the schema types.

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?

Opens with a precise verb set and resource: create/edit/pause/resume/delete "one of YOUR signals", and immediately narrows scope with the api:account requirement and the plain-language example "create a funding signal on HYPE". It further distinguishes itself from run_recommendation_pipeline and from list_signals, so an agent can identify the tool without opening the schema.

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?

Explicit routing decisions: Gambit Scan signals are set up in the app, not here; agent-created signals can only be paused or deleted here (403 on update/resume). It also directs the agent to list_signals view=catalog to discover valid predicate fields, which is the exact prerequisite an agent would otherwise miss.

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