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

Annotations already carry the safety profile (readOnlyHint, openWorldHint, idempotentHint all true, destructiveHint false), so the description starts at an advantage. It meaningfully adds context: the 'scheduled daily scan,' LLM-classification pipeline, ranking scheme, and frank disclosures that relevance is 'a compliance-triage signal, not legal advice.' Together these give the agent an accurate mental model of data origin and limitations.

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 most important fact in sentence one, then moves logically from purpose → return shape → parameters → disclaimers → workflow. Dense but not padded; the parentheticals '(free read)', '(default 168 = 7 days…)', and trailing 'Not financial advice.' are short and load-bearing. A very minor amount of redundancy between the opening scope list and the workflow section keeps this from a 5.

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 tool with no required parameters, an output schema, and four modest params, the description is complete: input semantics, output shape and ordering, use-case context, and disclaimers are all present. Rate limits, error conditions, and pagination are not mentioned, but those are minor given the described read-only, capped-lookback semantics.

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 a stark 0%, so the description carries the full burden — and nails it. It documents window_hours with units, default, and cap (168=7 days, capped at 720=30 days); min_relevance accepted values; agency options (SEC, CFTC, FinCEN); and the exact output fields ('relevance (high/medium/low) + score, matched topics, one-line factual summary'). Only caller_id isn't spelled out, but it's self-evidently a housekeeping param.

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+resource statement: 'Recent regulatory statements affecting Crank's scope' followed by explicit examples of what is returned (SEC/CFTC/FinCEN press releases, rule proposals). The description differentiates this from the similarly-named sibling get_technology_updates by scoping to regulators (SEC/CFTC/FinCEN), topics (DeFi, perps, tokenized equities), and classification criteria.

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?

Ends with an explicit workflow directive: 'check the current regulatory posture around perps, tokenized equities, or agent trading before acting on a strategy,' which tells the agent when to invoke it. However, it doesn't name alternative tools or explicitly state when NOT to use this one, relying on siblings section to imply the choices.

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