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

Discloses important behavioral details beyond the annotations: 'Costs 1 credit ($0.02 USDC),' 'Requires Authorization: Bearer tf_live_<64-char-hex>,' and notes that 'crypto legs were removed 2026-07-23 for market-data licensing compliance.' This goes well beyond the sparse readOnlyHint/openWorldHint/idempotentHint annotations, though it does not detail the exact output structure.

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 description is somewhat long but every sentence adds distinct value: premium positioning, added features, section list, cost, auth, free alternative, and a regulatory note. It is front-loaded and ends with a relevant caveat, with no filler.

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?

Covers the tool's purpose, usage condition, pricing, auth, section list, and a behavioral note about removed crypto legs. No output schema exists, but the section list implicitly conveys the payload shape. A minor gap is the lack of explicit response format description, but the description remains complete enough for practical invocation.

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?

The schema already documents the include parameter with 100% coverage, so the baseline is 3. The description adds practical meaning by explaining that it 'supports section filtering via ?include=' and listing the exact comma-separated values (earthquakes, hackernews, humans-in-space, launches, predictions). It also clarifies the default: 'Omit for all sections.'

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 description clearly identifies this as the 'Premium version of tf_briefing' and specifies that it 'Adds Polymarket prediction markets to the standard briefing payload.' It explicitly lists covered sections (earthquakes, Hacker News, humans in space, launches, prediction markets), which distinguishes it from the sibling tf_briefing.

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?

It states explicitly when to use this tool: 'Use when the agent needs prediction-market context in addition to the basic snapshot.' It also names the alternative, 'Free basic version (without predictions) available at tf_briefing (no auth required),' and notes 'Strict premium, no free trial.'

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