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

Even with readOnlyHint=true present, the description adds substantial behavioral context: the tool is free, a parsed shape not withheld data, based on ~71% brief coverage, content freshness limits, not real-time, and every payload carries stale/stale_days/built_from_brief_date. It also discloses refusal behavior with HTTP 400 for unsupported inputs. This goes far beyond the annotations and does not contradict them.

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 dense but every sentence adds meaningful information: functionality, freshness caveats, payload fields, risks, and input restrictions. It is front-loaded with the core purpose before warnings. Slightly run-on in the first sentence and a bit long overall, but there is no wasted 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?

With no output schema present, the description takes on the burden of explaining the return content and does so thoroughly: dated series, movement values, first/last brief, mention count, flip flag, and staleness fields. It also covers data freshness, real-time limitations, refusal behavior, and the payment parameter is covered by the schema. Nothing essential is missing for an agent to invoke this correctly.

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 100%, and the schema already documents both ticker and payment thoroughly, including the two-step payment flow. The description adds no parameter-specific details beyond reinforcing 'one ticker' and excluding portfolio/position/risk-profile inputs; that is useful but not necessary because the schema already carries the semantic weight.

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 states a specific function: parsing the full stance arc for one ticker into a dated series with movement, first/last brief, mention count, and flip flag. It is precise about the resource (one ticker) and the output shape, and it distinguishes itself from siblings by emphasizing it is a parsed shape derived from the published arc string, not a board snapshot or search result.

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?

The description implies when to use it via 'one ticker' and 'full stance arc,' but it never explicitly names a sibling alternative or gives a when-to-use/when-not-to-use rule. It does add useful exclusions (no portfolio/position/risk-profile inputs, not real-time), but it relies on the agent to infer the tool's niche relative to board_snapshot, latest_board, and search.

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