get_usage

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

Beyond the readOnlyHint annotation it discloses that the call costs nothing, that it also reports the server session budget (NEWSAPI_AI_MAX_TOKENS_PER_SESSION, default 200), and — importantly — that calls exceeding that budget fail locally without reaching the API. That is exactly the kind of failure-mode context annotations do not carry.

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 purpose, then usage, then the cost table, then the session-budget caveat. Every sentence carries actionable content, though the parenthetical cost list and the session-budget note make it longer than a purely minimal definition.

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 parameters, no output schema, and only a readOnlyHint annotation, the description still tells the agent everything needed: what it returns, when to call it, what it costs, and how the session budget can cause a local failure. Nothing material is missing.

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 tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further the description could add about parameter meaning, and it appropriately spends its words on cost behavior instead.

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?

States a specific verb and resource — 'Get the token budget of this NewsAPI.ai account' — and immediately enumerates what is returned (available, used, remaining for the current period). It is clearly distinct from the search/get/suggest siblings in the sibling list.

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?

Explicitly prescribes when to call it ('before a batch of searches') and supplies a concrete cost table for the alternatives (search_articles/get_article 1, search_events/get_event 5, get_trending_concepts 10), plus the note that suggest tools are free. That is a direct decision aid for choosing among siblings.

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