gdelt_tonechart

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

With no annotations provided, the description carries the full burden of behavioral disclosure, yet it only restates that a histogram is returned. It does not disclose the output format, binning scheme, GDELT's tone scale, or any limits or pagination behavior. The tool is low-risk as a retrieval operation, but the description adds no behavioral context beyond its purpose.

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 short at roughly 16 words, but it is redundant: 'Sentiment histogram' appears twice and the second sentence largely restates the first. The awkward 'for a query's matching' phrasing further weakens the structure. A single well-formed sentence would have earned a higher score.

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 and no annotations, the description must explain what the histogram contains, but it never does — no bucket count, no tone metric, no response shape. The 7-parameter interface with mutually exclusive time-window options (from/to vs timespan) is left entirely to the schema. An agent cannot predict the return structure of this tool from its definition.

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%, with all seven parameters documented in the input schema, so the baseline of 3 applies. The tool description's reference to 'a GDELT query' adds nothing beyond the schema's own query parameter documentation. The cross-reference to gdelt-search's query syntax lives in the schema, not in the description.

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 that the tool returns a sentiment (tone) histogram for a GDELT query, identifying the specific verb 'Return' and the resource. The explicit 'sentiment (tone)' focus differentiates it from sibling GDELT tools like gdelt_search and gdelt_timeline, though no sibling is named. The phrase 'for a query's matching' is grammatically awkward but the overall meaning is unambiguous.

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 offers no guidance on when to use this tool versus siblings such as gdelt_timeline, gdelt_context, or gdelt_search. Usage is only implied via the purpose statement, requiring the agent to infer that sentiment analysis is the differentiator. There are no exclusions, prerequisites, or alternative-routing hints anywhere in the description.

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