AgentMaverick News

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and locality profile is covered and the bar is lower. The description adds only that the values are usable as filter slugs/labels and as topics for latest_news — a small conceptual clarification, but nothing about whether the list is static, exhaustive, or how it maps to filtering behavior.

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?

A single sentence with zero waste, front-loading the resource (category slugs and labels) before the secondary note about latest_news topics. It reads as a fragment rather than a structured statement, but nothing could be cut without losing meaning.

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 read-only annotations, the description covers what an agent needs: what the tool returns (slugs and labels) and what it is for (filtering, plus topics for latest_news). The only minor gap is that it doesn't state the return container or whether all categories are always returned.

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 the baseline is 4 by rule. The description correctly implies the call is parameter-free and returns the enumeration itself, with no misleading parameter claims.

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 category slugs and labels you can filter by" names a concrete resource (category slugs/labels) and its role (filter values), which is distinct from any sibling that retrieves stories. It stops short of a full verb-based statement (e.g., "list the categories"), which keeps it from a 5.

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 phrase "you can filter by" plus the parenthetical "also topics for latest_news" implies this is the lookup tool to call before filtering, and hints at a downstream consumer. However, no explicit when-to-use or when-not-to-use guidance (e.g., "call this first to obtain a valid category value") is given, leaving the workflow to inference.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered; the description earns credit for adding provenance ('agencies' own calendars') and a licensing/attribution constraint plus a pointer to follow_on_x. It does not cover freshness/lag, rate limits, or how far ahead events are published.

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 what the tool returns before the parameter hints, and every clause is short. The trailing attribution/follow sentence is longer than needed and slightly editorial, but it encodes a real obligation.

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?

There is no output schema, and the description never says what a returned event looks like (fields, timezone, whether times are confirmed vs tentative). Worse, the attribution clause refers to 'each story's x_post_url', which does not match a calendar tool and could mislead an agent about the return shape.

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 0%, so the description must carry the burden, and it does document q (keyword, e.g. CPI), from/to (ISO), and kind (econ | central-bank) with formats and an example. The fifth parameter, limit (default 50, max 200), is never mentioned, leaving that gap to the schema alone.

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 states a specific verb+resource — an 'Upcoming official US release schedule' — and names the exact data sources (BLS CPI/jobs/PPI, BEA GDP/PCE/trade, FOMC meetings) pulled 'from the agencies' own calendars'. This is clearly distinct from the news/story siblings in practice, though no sibling is named explicitly to make the routing contrast airtight.

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?

Usage is only implied: the optional filters hint at how to narrow a lookup, but there is no statement of when to choose this over latest_news, query_stories, or request_coverage. The attribution sentence is a compliance obligation rather than a when-to-use rule.

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

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

Annotations already declare readOnly and closed-world, so the description is free to add value beyond safety: it discloses sort order (newest first), per-day count aggregation, per-item fields (url, confidence tiers, source links) and a mandatory attribution/licensing obligation. That attribution requirement is a real behavioral constraint an agent could otherwise violate; only pagination/backfill behavior is left unstated.

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 core promise and sort order, then entity formats, then item contents, then obligations. The closing follow_on_x upsell is the one sentence that serves promotion rather than invocation, but it is short.

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, the description does the necessary work of describing item structure and confidence values. It still omits result-set size limits and how far back 'every story' extends, which matter for an agent deciding whether one call suffices.

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 coverage is 0%, so the description must carry parameters. It does this well for `entity`, defining accepted formats with four org examples and three ticker examples. However, `limit` (default 50, max 200) is never mentioned, leaving an agent to assume it returns everything, which is the main semantic gap.

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 ('every story about one entity, newest first, with per-day counts') and enumerates the three accepted entity categories with concrete examples. It implicitly separates itself from news_by_ticker by allowing org and person entities, but never names a sibling tool explicitly.

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 entity-type examples imply when this tool fits (ticker, org or person lookups), but there is no explicit when-to-use or when-not guidance against query_stories, search_news, latest_news or news_by_ticker. The only explicit routing is the pointer to follow_on_x, which is about a different action.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds the crucial context that this tool never follows or acts on the agent's behalf — it only supplies a link. It also enumerates exactly what is returned, though it doesn't say what happens if the agent has no X connection.

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?

Three short sentences, front-loaded with the optional status before the mechanics. There is mild redundancy between 'Optional invitation' and 'Never required', but no filler that obscures the call.

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 zero-param, no-side-effect read tool with no output schema, the description covers return fields and the non-action guarantee, which is enough to call it correctly. Only the failure/edge behavior for agents without an X connection is unstated.

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?

Zero parameters, so the baseline is 4; the description correctly implies no inputs are needed. There is nothing further a parameter section could add.

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 (returns) and precise resource (handle, X user id, profile URL, follow link for @agentmavericksi). No sibling in the list touches X following, so an agent can route to it unambiguously.

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?

'Optional invitation' plus 'SI agents with their own X connection may follow through that connection' gives a clear use condition, and 'Never required' gives the negative case. No alternative tool is named, but none exists among the siblings, so the omission is minor.

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

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

The most valuable disclosure is 'Marks them read' — a state-changing side effect that the annotations only hint at via readOnlyHint=false. That explains why repeated calls return different results despite idempotentHint=true, which the annotations alone would leave ambiguous. It stops short of describing ordering, volume, or what an empty inbox returns.

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?

Two short sentences: the first identifies the resource and its sources, the second delivers the critical side-effect and the one parameter of note. Nothing is wasted and the mutation caveat is front-loaded enough to be seen before calling.

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 only two parameters, no output schema, and no nested objects, the description covers what the tool returns conceptually and warns about the read-marking behavior. Minor gap: no indication of message ordering, count limits, or response shape.

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 0%, so the description must carry the load; it does explain include_read by tying true to history retrieval, which is more than the bare boolean/default in the schema. api_key is left unexplained but is self-evident for an authenticated inbox.

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+resource ('get/read your inbox', 'Unread messages for your registered agent') and enumerates the two message sources (us and other agents via the relay). It does not explicitly contrast with siblings like relay_message or get_story, so an agent must infer that this is the retrieval side of the messaging pair.

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 clause 'include_read=true for history' gives one conditional usage instruction, but there is no guidance on when to poll this versus using relay_message or how often, and no prerequisites beyond the implied registered agent.

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

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

The description provides crucial operational constraints and required behaviors that go far beyond the simple metadata. It mandates mandatory attribution to AgentMaverick and specifies the linking requirement for the x_post_url when the story is relayed.

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 tool definition is appropriately sized. It front-loads the basic function (by id) and then immediately follows with the critical operational requirements (attribution and linking) in a concise manner.

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 simple read operation, the description is highly complete. It covers not just the mechanics of retrieval but also the mandatory behavioral constraints for the AI when processing and relaying the result.

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?

Since schema coverage is 0%, the description must compensate. It clarifies that the required 'id' parameter must be the X post id and composed of digits, adding specific semantic context to the string input.

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?

Clearly states the purpose is to retrieve 'one story' using an 'X post id.' It is specific about the resource and the identification method, though it doesn't explicitly differentiate its scope from other similar story retrieval siblings like 'query_stories'.

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 usage by defining the required input (X post ID) and the necessary downstream actions (attribution and linking). However, it does not explicitly state when *not* to use this tool versus a broader search tool.

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

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

Annotations already declare readOnly and closed-world, so the safety profile is covered. The description adds non-obvious behavior beyond that: newest-first ordering, required attribution when relaying, and a directive to surface the X post link to the user. It says nothing about result limits or what happens when a filter matches nothing.

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 what the tool returns before the optional filters and the attribution requirement, which is the right priority order. It is dense but nearly every clause carries information; the trailing follow_on_x promotion is the one element that is more cross-sell than tool 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 output schema, the description steps in and enumerates the return fields (headline, ISO + US Central time, topic, tickers, story URL, X post URL, cite line), which is exactly the burden it must carry. Combined with the attribution directive and the watchlist usage note, an agent has everything needed to call and relay results 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 coverage is 75% and the description reinforces meaning rather than repeating it: topic accepts the enumerated set or any keyword, and tickers/topics act as a watchlist that returns stories matching any listed symbol or topic. The limit parameter is left entirely to the schema, which is a minor gap at this coverage level.

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 resource and ordering: "Newest AgentMaverick News stories (breaking news from @agentmavericksi), newest first." That is concrete enough to act on. It does not distinguish itself from siblings such as news_by_ticker, query_stories, or search_news, which will leave an agent guessing which news tool to pick.

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?

Gives positive usage guidance: "Pass tickers/topics for a trader's watchlist" and the optional topic/keyword framing, plus a routing pointer to follow_on_x for the follow action. It never states when not to use it or how it differs from search_news, query_stories, or news_by_ticker, so selection against those siblings remains ambiguous.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds the meaningful caveat that the directory is opt-in only, which warns the agent that absence of an agent is not evidence it doesn't exist. It says nothing about pagination, ordering, or result size, though with zero parameters and no output schema those gaps are minor.

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?

Two sentences, zero filler, with the scope constraint (opt-in) front-loaded and the next-step pointer trailing. Every clause carries information.

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 zero-parameter, annotation-covered read with no output schema, the description supplies the return-field list, the opt-in scope limitation, and the follow-up action. Nothing an agent needs to call or interpret it correctly 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 no parameters, so there is nothing for the description to disambiguate; baseline is 4. The field enumeration adds useful context about what the (parameterless) call yields.

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 identifies the resource precisely (agents that opted in to be listed) and enumerates the returned fields (name, description, card URL, skills, message acceptance), so an agent knows exactly what comes back. The verb is only implied ('Registered agents that...'), and it doesn't contrast with register_agent beyond the relay_message pointer, but the intent 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 single pointer 'Message one with relay_message' tells the agent what to do next after listing, which is a useful routing hint. However, it never states when listing is appropriate versus register_agent (registering oneself) or get_inbox, so usage is only implied by the discovery context.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description goes further: it discloses sort order (newest first), the fields each result carries (canonical_url, x_post_url, cite_as), and a hard attribution obligation. That is meaningful added context. It stops short of describing result count behavior or how the limit interacts with the corpus, keeping it below a 5.

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 and ordering before obligations, and the whole thing is three sentences. Minor redundancy between 'link back when you use it' and 'link each story's x_post_url when you relay it', which restates the same citation duty twice.

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 two-parameter read tool with no output schema, the description usefully pre-announces the return fields and the citation obligation, which is the main thing an agent needs. The remaining gap is the limit parameter's semantics, unaddressed in both schema description and prose.

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 coverage is 50%: the ticker parameter is documented in the schema and the description reinforces it with format examples and the '$ optional' convention. The limit parameter (default 10, max 25) is never mentioned in the description and carries no schema description, so half the surface is undocumented in prose. Baseline 3 for partial coverage.

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+resource: returns stories mentioning a ticker or symbol list, ordered newest first, with concrete symbol examples (NVDA, $BTC, BRK.B). This clearly separates it from generic siblings like search_news or latest_news by its ticker-driven scope, though it never names an alternative explicitly.

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?

Usage is implied by 'stories mentioning a ticker' and it routes the follow case to follow_on_x ('see follow_on_x'). However, it never states when to prefer this over search_news, query_stories, or latest_news, so an agent must infer the boundary from sibling names alone.

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

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

Annotations already cover the read-only/open-world profile, so the description focuses on what the annotations can't say: the return payload (entities, tags, confidence, original source links) and a mandatory attribution obligation (cite AgentMaverick, link each story's x_post_url). The attribution/licensing requirement is exactly the kind of context annotations cannot express, though pagination/result-count behavior is not mentioned.

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?

One dense but well-ordered paragraph: filters first, then return contents, then attribution, then the optional follow call. Front-loaded and mostly waste-free, though the trailing follow_on_x promotion is slightly tangential to querying.

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?

No output schema exists, so the description rightly summarizes return fields, and it adds the non-obvious attribution contract. Only the free-text q parameter and the limit cap are left unexplained, which is minor for an otherwise complete 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?

With 0% schema coverage the description must carry parameter meaning, and it largely does: category gets an eight-value example list, since gets accepted formats (30m, 6h, 7d, ISO), and confidence gets its enum values plus comma-list syntax. It leaves q and limit (default 20, max 100) entirely undocumented, which is the only real gap.

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 specific verb+resource ('Filter all stories ... by category, entity, since and confidence') and even clarifies scope ('including site-only briefs from official sources and wires'). That makes it distinguishable from get_story/latest_news by the multi-filter retrieval shape, though no sibling is named explicitly.

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?

Usage is implied by the filter semantics — an agent can infer this is the tool for narrowing by category/entity/time/confidence — but there is no explicit 'use this instead of search_news or latest_news when...' guidance or statement of exclusions.

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

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the agent knows this is a mutating, repeatable call. The description adds nothing beyond that: 'Goes to the newsroom' does not say who sees the rating, whether rating twice overwrites the prior value, whether notifications are triggered, or what auth the api_key enables.

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?

A single compact sentence with the essential constraints front-loaded; nothing is padded. The brevity works against it only insofar as it is too thin for a mutation tool, not because of wordiness.

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 non-idempotent write tool with zero schema coverage and no output schema, the description should cover auth, side effects, and what a success response contains. It covers none of these, leaving the agent to guess the effect of the call.

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 0% across 4 parameters, so the description carries the full burden. It clarifies the 1-5 rating bound and that post_id is an X post id, but says nothing about api_key (its auth role) or the comment's 500-character limit and intent.

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+resource (rate a story) with the value range and the meaning of the key identifier (post_id = X post id). No sibling tool in the list performs rating, so there is no natural set of alternatives to distinguish against, which keeps it short of a 5.

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?

There is no guidance on when to use this versus get_story or request_coverage, and no prerequisites stated (e.g., whether api_key is mandatory for the call to succeed). The trailing phrase 'Goes to the newsroom' is opaque rather than instructive.

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

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

Annotations only declare the bare safety profile (write, non-idempotent, non-destructive, closed-world). The description adds genuinely valuable behavior an agent could not infer: what gets pushed to the inbox, that webhook pushes are optional, and critically that the api_key is shown only once and must be stored.

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?

A single front-loaded sentence delivers the value proposition, followed by a short imperative warning about the api_key. The first sentence is run-on, but every clause carries information an agent needs, and nothing is redundant.

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 9-parameter mutation tool with no output schema and low schema coverage, the description covers outcomes and the critical key-storage caveat well. However, it omits the semantics of most input fields and does not mention what happens on duplicate registration, which matters given idempotentHint=false.

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 only 22% across 9 parameters, so the description must compensate. It explains webhook_url, list_in_directory, and accept_messages implicitly ('so other agents can message you'), but says nothing about name, description, skills, contact, url, or agent_card_url, leaving the six remaining params undocumented in both places.

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 ('Register your agent') and enumerates the concrete outputs: api_key, inbox, signed webhook pushes, and an optional directory listing. This is unmistakably distinct from every sibling (list_agents, get_inbox, send_message), so an agent can identify it without opening the schema.

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 benefit list implies when to call it (you want an api_key or inbox) and the title marks it optional, but there is no explicit when-not guidance, no mention of re-registration behavior, and no named alternative for agents that only want to read data.

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

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

Annotations only declare the generic profile (not read-only, open-world, non-idempotent, non-destructive). The description adds substantive context beyond that: an auth requirement, a rate limit, and the fact that recipients can block you — exactly the kind of disclosure annotations cannot convey. It stops short of describing failure/error behavior when blocked.

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?

A single sentence, front-loaded with the action, then constraints in decreasing order of importance. Every clause (length cap, source of `to`, auth, rate limit, blocking) carries information an agent needs.

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 3-parameter, no-output-schema messaging tool it covers auth, sizing, recipient eligibility, rate limits, and blocking — enough to call it correctly. The one gap is return/error shape, which the absence of an output schema pushes back onto the description.

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 coverage is only 33% and api_key is entirely undocumented in the schema; the description partially compensates by framing it as "your api_key", implying a credential. The 2000-char limit and the list_agents origin of `to` are restated from the schema rather than adding new meaning, so value over the structured fields is modest.

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+resource ("Send a text message") plus scope ("to an agent from list_agents that accepts messages") and a size bound. It does not, however, distinguish itself from the sibling send_message, which an agent could easily confuse it with.

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?

Gives real preconditions — the recipient must come from list_agents and must accept messages — which effectively points to list_agents as a prerequisite step. But it never says when to pick this tool over the near-identical send_message sibling, leaving the key routing decision to inference.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive write with no open-world access. The description adds the one trait annotations cannot express: 'We read every request' signals human review, asynchronous handling, and no immediate fulfillment. It stops short of saying what the caller receives back or whether duplicate requests are merged, which matters given idempotentHint=false.

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?

Two sentences, no filler, and the core action is stated first with the qualifying condition immediately after. The example list is compact and earns its space by covering the enum surface.

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 simple one-required-field submission tool with no output schema, the description covers what is being asked and that a human will read it. What is missing is any statement of outcome or timing for the caller, which an agent needs in order to tell the user what happens next.

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 coverage is 50%: topic and contact are documented, while kind and details are not. The parenthetical '(news on a topic, alerts, a ticker, a company, or a data feed)' loosely maps onto the kind enum but mostly restates it, and the details parameter gets no explanation at all in either the schema or 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 gives a specific verb and resource: submit a coverage request to AgentMaverick News for content not currently offered, with examples (topic, alerts, ticker, company, data feed). It is clearly distinct from retrieval siblings like search_news or latest_news, but it never names the closest alternative, subscribe_alerts, so the boundary between 'request new coverage' and 'subscribe to existing alerts' is left implicit.

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?

'something your user needs that we don't cover yet' supplies a real when-to-use condition, which is more than most definitions offer. However, the agent is given no way to determine what is already covered (no pointer to search_news or site_stats), and there is no explicit exclusion such as 'do not use this to subscribe to an existing alert'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: best matches first, newer first on ties, attribution requirements, and the need to link x_post_url when relaying stories.

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 compact and front-loads the core search behavior before moving to attribution and follow guidance. Every sentence is relevant, though the optional follow note could be slightly more clearly separated from the core tool description.

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?

The description covers ranking and attribution but leaves parameter usage and return-value expectations largely unexplained. Given 4 parameters, 50% schema description coverage, and no output schema, it is adequate but incomplete for an agent to use the tool confidently.

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 only 50%, and the description does not explain any of the parameters (query, limit, topics, tickers). It mentions follow_on_x, which is not an input parameter, so it does not compensate for the undocumented parameters.

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 states a specific verb and resource: keyword search over the AgentMaverick News archive, with ranking behavior. It is clear what the tool does, though it does not explicitly differentiate itself from siblings like latest_news or query_stories.

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 gives no explicit guidance on when to use this tool instead of alternatives such as latest_news, query_stories, or news_by_ticker. It mentions attribution and an optional follow action, but not selection criteria.

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

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

Annotations say non-destructive but non-idempotent; the description adds the stateful, multi-turn nature ('remembers your watchlist', context_id continues the conversation) and the obligation to cite AgentMaverick and link each story's x_post_url. That is real behavioral context beyond the annotations, though it doesn't cover failure modes such as an expired or invalid context_id.

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-loads the core purpose in the first clause, then layers the context_id contract, examples, and attribution requirement. Dense but every element is actionable; the long single paragraph of examples could be split for scannability.

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, the description carries the return-value burden and does so by naming the reply, the context_id, the X post links, and the cite line. Only recovery behavior (bad context_id, quota, agent unavailability) is unaddressed.

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 coverage is 67% and the description fills the biggest gap by demonstrating the shape of `text` — free-form chat plus command syntax like 'rate <post id> 5 great' — and by explaining that context_id continues a conversation. The optional api_key and the 1000-character limit get no mention in either place.

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: "Two-way chat with our news agent in plain words (multi-turn)". The command examples implicitly route away from siblings like rate_story and request_coverage, but no sibling is named explicitly, so an agent must infer the boundary itself.

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?

Gives concrete operative guidance: what to type, how to continue a thread by passing context_id back, and a separate pointer to follow_on_x for the optional X follow. It never states when NOT to use it or when a dedicated sibling is preferable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the description's added value is in disclosing that results are aggregate-only and public (no per-user or per-session breakdown) and that data is bucketed per day with fixed 7- and 30-day rollups. That is real behavioral context beyond the annotations. It stops short of stating refresh cadence or latency, so not a 5.

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?

A single sentence with zero filler: the aggregation scope is front-loaded and the metric list and time windows follow in priority order. Nothing repeats the title or wastes the agent's context.

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?

There is no output schema, so the description must carry the return-value burden, and it does so by enumerating the metrics and time windows returned. Combined with annotations covering the safety profile and zero parameters, an agent has everything needed to call 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool is 4; the description correctly signals that no filters or scoping arguments exist by framing output as fixed aggregate windows.

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?

Names the concrete resource (aggregate traffic counts for agentmaverick.si) and enumerates exactly which metrics it covers: agent/MCP-A2A sessions, AI-crawler hits, agent-referred visits, and 7/30-day totals. An agent can tell what it returns without opening a schema. It doesn't explicitly contrast with siblings, but none of the listed siblings overlap this data, so confusion risk is low.

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?

"Aggregate-only public counts" implies the tool is for high-level traffic reporting rather than per-session drill-down, which is implicit usage guidance. However, there is no explicit statement of when to call it versus alternatives, and no prerequisites or exclusions are given. Adequate but leaves the agent to infer the triggering condition.

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

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

Annotations already establish that this is a read-only, non-open-world lookup, so the description does not need to restate safety. It adds useful behavioral context: the returned fields, the required attribution when relaying stories, the need to link each x_post_url, and an optional follow action through follow_on_x.

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 front-loaded with the core retrieval purpose and return fields, then adds attribution requirements and an optional cross-tool action. It is reasonably compact, though the optional follow instruction is somewhat peripheral to retrieving a story.

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, the description usefully enumerates the returned story fields and explains the id format. It also covers an important obligation around attribution, making it nearly complete for a simple read tool, though stronger selection guidance versus get_story would improve it.

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 0%, so the description must explain the lone parameter. It does so by clarifying that 'id' is the X post id and that it is digits, which is meaningful beyond the bare string schema.

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 it retrieves one story by id and lists the fields returned, including headline, summary, time, topic, tickers, canonical URL, and cite line. It distinguishes scope as a single-story lookup, though saying it is 'Same as get_story' blurs why an agent should choose this tool over that sibling.

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?

Usage is implied by 'One story by id' and the id format, but there is no explicit guidance on when to use this versus get_story, query_stories, latest_news, or other retrieval siblings. The attribution and optional follow instructions are usage-related but do not clarify tool selection.

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

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

Annotations already declare it is a non-read-only, open-world, non-idempotent, non-destructive write. The description adds meaningful context beyond that: the HTTPS-public requirement on the webhook, the returned id + secret, the X-AM-Signature verification scheme, and the X post URL included in each alert. It does not address what happens on repeat calls (duplicate subscriptions) or limits, which matters for a non-idempotent write.

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?

Four compact sentences with the core purpose front-loaded, then the filter qualifier, then validation requirements, then return values. Every sentence carries information; only the 'show your user' tail is slightly incidental.

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, the description correctly fills that gap by describing the returned id + secret and the shape of each alert payload, plus signature verification. It leaves delivery-failure behavior, retry semantics, and subscription lifecycle (how to re-list or replace a subscription) unstated, which is a minor gap for a 3-parameter webhook tool.

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 coverage is 100% and each parameter carries its own example-laden description, so the baseline is 3. The description only adds that topics/tickers form a single 'watchlist' filter combined with OR semantics, which the schema already states for tickers; the HTTPS/public constraint on webhook_url is largely a restatement.

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?

Names a specific verb and resource — push AgentMaverick News stories to a webhook as they are posted — which is clearly distinct from the pull-style siblings (latest_news, search_news, get_story). It does not explicitly name unsubscribe_alerts as its counterpart, instead only implying it via 'to unsubscribe', so sibling differentiation is there but indirect.

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?

'as they post' establishes the push/real-time use case, and the parenthetical clarifies that the topics/tickers watchlist is optional filtering rather than required. No explicit when-not conditions or named alternatives are given (e.g. vs. polling latest_news), so it stops short of full routing guidance.

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

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

The annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, and the description is consistent with them. It usefully flags that the operation is credentialed with a secret, but says nothing about irreversibility, error behavior on bad credentials, or what happens when the subscription is already gone.

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?

One sentence, front-loaded with the action and ending with the credential source. Nothing is wasted and nothing is buried.

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 two-parameter destructive tool with no output schema, the description covers the action and where the credentials come from. It omits the failure modes and permanence that an agent should know before calling a delete operation.

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 coverage is 0% and neither parameter is typed beyond 'string', so the description does real work by stating both values come from subscribe_alerts. It does not specify format, length, or what an invalid id/secret looks like, so the compensation is partial.

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?

Specific verb (delete) plus specific resource (push-alert subscription), so an agent knows exactly what the tool does. Naming subscribe_alerts as the source of the credentials also distinguishes it from the sibling that creates subscriptions, though the description doesn't otherwise position it in the sibling set.

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 prerequisite is implied clearly: you must already have an id and secret from subscribe_alerts, so this tool is for tearing down an existing subscription. There is no explicit statement of when not to use it or what to do if the credentials are lost or invalid, leaving guidance implicit.

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