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

Annotations already declare readOnlyHint=true, so safety is covered; the description adds meaningful behavior by revealing that a theme summary plus a semantic news search run server-side and that an LLM curates the hooks, which implies latency and non-determinism. That value is undercut by noise like the '/tmp/mcp-gate/cta_tool.js' validation path and the hedge about direct probes vs. the summary composite, which mean nothing to an agent and read as internal changelog.

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?

The purpose is buried behind implementation jargon ('graph's moat', 'theme_summary(has ripple/entities/aspects)', 'summary composite') and a file path. The most useful sentence for an agent — propose 1-2 data-backed hooks — is first, but the trailing material does not earn its place.

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 two-parameter, read-only tool with no output schema, the description conveys that 1-2 curated hooks are returned, which is adequate. It still leaves unclear whether the result is a rendered suggestion list, whether it mutates conversation state, and how failures or empty data-backed results are surfaced.

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 100% and both parameters are documented in the schema, including the window enum values and the note that price history is unaffected. The description adds nothing about what 'theme' should look like or which theme formats produce good hooks, so 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?

The core verb+resource is present ('propose 1-2 data-backed "explore further" hooks'), but half the description is spent on an internal server-side pipeline (theme_summary, semantic news search, deepseek curation) rather than on what the tool returns to the caller. An agent can roughly infer it generates follow-up suggestions, yet it never cleanly states the deliverable shape or how it differs from calling theme_summary or search_news directly.

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?

'After answering' gives a timing cue for when to invoke it, which is genuinely useful context. However, there are no exclusions, no statement of when to call theme_summary or search_news instead, and no guidance on choosing a theme or window, so usage is only implied.

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