Muhabbit

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

Beyond the readOnly/openWorld annotations, the description discloses concrete operational behavior: an unconfirmed alert answers 403 alert_unconfirmed unless include_unconfirmed is true, and the default route is free only for confirmed alerts. The payment model (x402, API key, or wallet token on a paid plan) is stated, which is exactly the kind of auth/cost context annotations cannot express.

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 core provenance and 403 behavior is front-loaded in the first two sentences, which is good. The trailing parenthetical then restates the free/paid conditions already given, making the passage denser than necessary.

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 covers the response contents, id provenance, the error case, and the payment gate. An agent has everything needed to call it correctly and to anticipate the 403 outcome.

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%, so the baseline is 3, but the description adds value the schema lacks: it states that include_unconfirmed defaults to false, that the false route is free for confirmed alerts, and that the true route is paid and unlocks suspected alerts. The uuid format of id and the article_id alternate form are already in the schema, so the addition is meaningful but incremental.

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 names a specific resource (one exchange security alert) and lists what it returns (evidence signals, sources, timeline), which clearly distinguishes it from the sibling list tool muhabbit_alerts. The retrieval verb is implied by the noun phrase plus 'Takes the id from...' rather than stated outright, so it falls just short of a fully explicit verb+resource statement.

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 explicitly tells the agent where the identifier comes from — an id from muhabbit_alerts or the article_id of a headline in muhabbit_events — which is exactly the routing information needed. It gives no explicit 'do not use when' case (e.g., when browsing multiple alerts), but the provenance guidance is clear and actionable.

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?

Beyond readOnlyHint/openWorldHint, the description discloses the access model that materially changes behavior: confirmed tier is free with no credentials and a hard 20-item cap, while suspected/all require x402 payment, an API key, or a wallet token on a paid plan. Ordering (newest update first) and the informational-not-advice disclaimer are also stated. Pagination/error behavior and the polling/dedupe nuance are left to the schema rather than the description.

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?

Purpose and signal types are front-loaded in the first sentence, followed by payload shape, then usage triggers, then access terms. The parenthetical pricing block is dense and partly duplicates the tier parameter description, but no sentence is fully wasted.

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-shape burden and does so: one item per incident listing tier, exchange, headline, USD at risk, assets, evidence signals, timeline, and record links, plus sort order. Access gating and the free-tier cap are also covered, so an agent knows what it will get and what it will cost before calling.

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%, so all four parameters are already documented in the schema, including tier semantics and the since polling guidance. The description restates tier (suspected = unconfirmed, confirmed) and echoes the free-feed 20-item cap, adding little beyond the structured fields — baseline 3 is appropriate.

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 concrete verb+resource (exchange hack and drain alerts from an incident engine) and enumerates the signal types it covers (large outflows, withdrawal halts, researcher posts, exchange statements). It never names the near-duplicate sibling muhabbit_alert (singular), so the agent cannot tell from the description alone which of the two to open for a single incident.

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?

Explicit trigger phrases are given — 'is an exchange being hacked right now?' and 'any exchange incidents since T?' — which map cleanly onto the free default feed versus the since-parameterized query. There is no stated exclusion or named alternative for looking up a single known incident, so routing vs muhabbit_alert is left implicit.

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 authentication context beyond the annotations, but its auth statement is internally confusing: it says the anonymous token is enough and then says an API key or wallet token is needed.

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 and front-loads the data it returns, but the parenthetical authentication sentence is ambiguous and undercuts clarity. It earns partial credit for brevity but not for clean structure.

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 read-only tool with no output schema, the description should make the return shape clear. It states the general content ('Verticals and currently active topic slugs') but does not specify the response structure, and the authentication wording is contradictory.

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 has zero parameters, so there is no parameter semantics to explain. The baseline for a zero-parameter tool is 4.

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 names the data exposed ('Verticals and currently active topic slugs') but does not use a clear verb such as 'list' or 'get'. It is identifiable as a categories resource, but the operation is only implied rather than stated.

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 authentication details but does not say when an agent should use this tool versus the many sibling tools such as muhabbit_search or muhabbit_narratives. There are no explicit usage conditions or 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?

The description adds critical behavioral information regarding authentication that is not present in the annotations. It explicitly states that an API key or wallet token (X-API-Key or Authorization: Bearer) is required for the tool to function.

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 definition is highly efficient, using two sentences to convey the 'why' (usage), the 'how' (5 factors), and the 'how-to-authenticate' (API key requirements) without any wasted words.

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?

Given the tool is a lookup function with minimal input and no output schema, the description is maximally complete. It addresses the required input type (article ID) and essential external requirements (API key), leaving no major operational gap for the agent.

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 the input schema only defines a simple UUID, the description provides the necessary semantic context by explaining that the tool operates on 'one article.' It also elaborates on the complex 5-factor scoring mechanism, which is not captured in the 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 defines the tool's purpose as calculating a 5-factor confidence score for a single article. By listing the factors (source tier, freshness, etc.), it differentiates this function from broader sibling tools like search or sentiment analysis.

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 provides strong usage guidelines by instructing the agent to use the tool 'BEFORE treating a headline as tradeable or citing it as fact.' This establishes a clear context for when the tool is necessary and when it is not.

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 valuable operational context by stating that an API key or wallet token is required in X-API-Key or Authorization: Bearer form, which is not present in the schema or annotations.

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 two compact sentences. It front-loads the usage trigger, follows with the core operation, and ends with the authentication prerequisite without unnecessary repetition.

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 single-purpose read-only validation tool, the description covers purpose, trigger scenarios, and auth requirements. However, with no output schema, it does not indicate what the validation result contains, such as whether it returns sources, confidence, or a simple confirmation.

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?

There is only one parameter, article_id, and schema description coverage is 0%. The description implies that an article is being validated, but it does not explain the parameter's role, expected UUID format, or how to obtain an article ID, so it does little to compensate for the missing schema documentation.

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 function: multi-source validation of an article's claims with entity correlation. An agent can understand the resource and operation, though it does not explicitly differentiate this from nearby siblings such as muhabbit_confidence or muhabbit_record_verify.

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 gives explicit trigger questions ('is this confirmed?' and 'who else is reporting this?') that map directly to when this tool should be used. It does not provide when-not-to-use guidance or name alternative tools, but the usage context is clear.

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?

Goes well beyond the readOnly/openWorld hints: it discloses the 'Unconfirmed:' prefix convention, that the feed is a hash-chained public record, the meaning of all three UTC ms clocks, ascending impact range, cursor paging, and that no credentials are required. These are call-relevant behaviors an agent could not infer from annotations alone.

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 resource and ordering, and every clause carries information (clocks, prefix convention, sibling pointer, auth status). It is dense to the point of being a single packed paragraph, but there is little outright waste.

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 still tells the agent what each returned item contains (headline, three timestamps, focus tags, category, impact 0-100) plus pagination and free-tier access. Nothing needed to call or interpret results 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?

Schema coverage is 100%, so the schema already documents limit, cursor, categories and min_impact fully. The description only adds 'Page with next_cursor', which is marginally more than the schema states; the impact range and category list merely restate schema content. Baseline 3 applies.

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 (public market-event feed) with explicit scope ('every headline Muhabbit's wire published, newest first') and enumerates the covered categories. An agent can distinguish it from muhabbit_news and muhabbit_categories without opening any 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?

Gives clear usage context and routes one case explicitly: unconfirmed exchange security alerts live here, but 'their evidence is in muhabbit_alerts', naming the sibling to follow up with. It stops short of stating when to prefer muhabbit_news or muhabbit_search over this feed, so no full when/when-not matrix.

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 meaningful behavioral context beyond annotations: the 15-minute capture cadence and the authentication requirement via X-API-Key or Authorization: Bearer. It does not describe pagination or exhaustive return behavior, but it adds enough context for a read-only time-series tool.

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 purpose, then usage guidance, then an auth note. Every sentence contributes necessary information, and there is no redundant restatement of the tool name or schema. It is appropriately sized for a two-parameter read tool.

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?

Given the simple schema, full parameter description coverage, annotations, and lack of an output schema, the description provides enough detail to call the tool correctly. It covers purpose, usage sequencing, data cadence, and auth requirements. No critical operational detail for this tool appears to be 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?

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces that the tool operates on one narrative but does not add syntax, constraints, or examples beyond what the schema provides. Baseline 3 is appropriate because the schema carries the parameter semantics.

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 resource and scope: a time series for ONE narrative, including 15-minute captures of phase, velocity, article and source counts. It also distinguishes this tool from the sibling muhabbit_narratives by framing this as a follow-up for lifecycle evolution. An agent can tell what the tool returns and when it differs from the related list tool.

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 explicitly says to use this after muhabbit_narratives to see how a story's lifecycle evolved, including the question it answers ('accelerating or rolling over'). This gives both the prerequisite sibling call and the intended analytical use case. The guidance is clear enough that an agent does not need to infer when to choose this over muhabbit_narratives.

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 two genuinely useful items beyond that — the auth requirement (X-API-Key or Bearer token) and the return shape ('decision-ready rows, not a raw feed'). It still says nothing about rate limits, result caps, or freshness/lag of 'live' clusters.

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 verb and ranking criteria, then use cases, then the auth caveat as a trailing parenthetical. Two sentences with no filler; the auth note is slightly tacked-on but earns its place as a prerequisite.

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 enough: it tells the agent the result is pre-ranked rows with phase/velocity/source-count rather than a feed, and flags the credential requirement before the call. The remaining gap is that the two optional parameters are left entirely to the schema.

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 mentions neither parameter. 'vertical' has four enum values (crypto, finance, tech, turkish) whose selection semantics are unexplained, and 'emerging_only' is never addressed. An agent can guess from the names, but nothing is confirmed.

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 concrete verb+resource with its ranking criteria ('Ranked live narrative clusters by phase, velocity and distinct-source count'), which is far more specific than the bare title 'Narratives'. It doesn't explicitly name muhabbit_narrative_history as the contrasting tool, so differentiation relies on the agent inferring 'live' vs. 'history' from names.

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 use cases ('themes, rotations, or "what's the story in crypto right now?"') that map cleanly to an agent's intent matching. It stops short of stating when NOT to use it or naming the sibling (narrative_history) that handles historical lookups.

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 readOnlyHint and openWorldHint, so the description's addition of the paid-access requirement ('API key, wallet token, or x402 payment') is genuinely valuable context an agent cannot get elsewhere. It also discloses the 'approved' curation filter, though it omits pagination behavior and whether the payment/gating failure mode returns an error or empty set.

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?

Hmm — the description is compact: three sentences, no filler, purpose front-loaded. The 'Agent-shaped items' sentence is jargon but earns its place by describing the return payload in the absence of an output schema. This is efficient overall.

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 correctly spends a sentence enumerating returned fields (signal, tokens[], narrative_id, context, sentiment_value). Combined with the payment note, an agent knows purpose, gating and payload shape. It falls short only on the three unfiltered parameters and on failure/empty-result behavior.

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 29%, so the description must compensate. It maps roughly onto four of seven parameters (vertical, topic=category, tokens, time=since) but leaves limit, language and min_importance undocumented in both places, and adds no format detail for tokens beyond what the schema already says.

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: 'Latest approved news across crypto, finance, tech and Turkish markets,' and even names the item shape the agent gets back. It is clearly distinguishable from stats-oriented siblings like muhabbit_sentiment_index or muhabbit_ticker_summary, but it never explicitly contrasts with the closest sibling, muhabbit_search, so an agent must infer which is the right retrieval path.

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?

'Filter by vertical, topic, tokens or time' implies the intended usage pattern but gives no when-to-use/when-not guidance and no alternatives. With muhabbit_search, muhabbit_events and muhabbit_narratives in the sibling set, an explicit routing rule would materially help and is absent.

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 readOnly and closed-world, and the description adds traits they cannot express: the output is pre-scheduled rather than on-demand, it is English-only, and access is gated behind a paid route (API key, wallet token, or x402 payment). That payment prerequisite is exactly the kind of context an agent needs before calling. It still doesn't say what happens on an unpaid/unauthorized call or what "freshness" is measured against.

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 tight sentences with the resource and cadence front-loaded and the payment caveat demoted to a trailing parenthetical. "Returns freshness" is the one vague clause that doesn't quite earn its place without elaboration.

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 parameter descriptions, the description carries the full burden, and it covers scheduling, language, and payment but not the shape or volume of a recap (how many items, what counts as "freshness"). Defaults for the optional vertical/timeframe pair are also unstated, so an agent must guess how to call it minimally.

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%, but both parameters are closed enums that document their own allowed values. The description restates those values (timeframes, "vertical or all verticals") and adds the language constraint, but does not explain defaults, whether the two parameters interact, or what each vertical bucket contains.

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?

"Scheduled 1h / 24h / 7d recap for a vertical or all verticals" names a concrete resource (recap), its cadences, and its scope, which an agent can distinguish from news/search siblings. It stops short of naming a specific sibling it should be preferred over, so differentiation is inferential rather than explicit.

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?

"never generated on demand" and "Returns freshness" together imply this is a read-only pull of pre-computed scheduled output, which is useful when-not guidance. However, no alternative sibling is named (e.g., muhabbit_news or muhabbit_ticker_summary for on-demand content), so routing between tools is left 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 cover the read-only and closed-world profile, so the description's added value is real: it discloses the free/no-credentials access model, the chain-ordered pagination contract via next_from, and the exact hash construction. It does not state ordering guarantees on page boundaries or what happens when an id is out of range, which would be the remaining behavioral gaps.

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 what the tool returns before the technical hash detail, and every clause carries information. The hash-recipe sentence is dense and slightly specialized, but it is justified for a verification-oriented endpoint, and the parenthetical about credentials is well placed.

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 compensates by enumerating the returned fields and the pagination token. 'Frozen fields' remains undefined, leaving some ambiguity about the record payload shape, which prevents a 5.

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%, with both `from` and `limit` fully documented including defaults and bounds, so the schema does the heavy lifting. The description only loosely reinforces this ('from an id', 'Page with next_from') and adds no format or edge-case detail beyond the schema, matching the baseline 3.

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 ('Raw public record entries in chain order from an id') and names the returned fields (frozen fields, prev_hash, hash), so an agent knows this is the raw ledger fetch. It does not explicitly contrast with siblings like muhabbit_record_head or muhabbit_record_verify, which is the only thing keeping 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?

'For offline verification' and 'Page with next_from' imply the use case and pagination flow, and 'Free: no credentials needed' signals costless access. However, there is no explicit statement of when to choose this over record_head or record_verify, so the agent must infer the routing from the sibling names.

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?

Goes well beyond the readOnlyHint/openWorldHint annotations: it explains the underlying append-only sha256 hash-chain structure, that the value is null on an empty record, and that no credentials are required. These are exactly the operational details an agent needs to interpret the result confidently.

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 tight sentences: what is returned, what it means cryptographically, and how to use it later. The essential identity of the return value is front-loaded, and the free/no-credentials note is a useful trailing qualifier rather than 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 and no parameters, the description must carry the return-value explanation, and it does: latest entry id, hash, and null-on-empty. Annotations cover the safety profile, and the description covers everything else an agent needs to call and interpret it 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 the baseline is 4 — there is nothing for the description to disambiguate about inputs. It correctly spends no words on parameters and instead invests in explaining the returned head value.

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 the latest entry id and hash of the public record — and immediately qualifies the record as an append-only sha256 hash chain (hash_v1). An agent can distinguish this checkpoint tool from muhabbit_record_entries and muhabbit_record_verify without opening any 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?

"Pin the head now; muhabbit_record_verify later proves nothing up to it was rewritten" gives explicit sequencing and names the complementary tool, so the agent knows the pin-then-verify workflow. It never states when NOT to use it (e.g., to enumerate entries use muhabbit_record_entries), so it falls short of full alternative routing.

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 readOnly and closed-world behavior, and the description adds substantial context on top: a 5-calls-per-minute rate limit, the exact result shape (ok, checked, head_hash), and the enumerated failure reasons (prev_hash_mismatch, hash_mismatch, endpoint_missing). The credential-free note removes a common pre-call blocker.

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 paragraph that leads with the action, then bounds, then return shape, then rate limit and auth. Every clause carries information an agent needs; nothing is repeated from the schema or annotations.

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, but the description fully compensates by naming the success fields and every error reason. Combined with the limit and default-window rules, an agent has everything needed to call and interpret this tool 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 100%, so the baseline is 3, but the description adds real meaning: the 1000-entry cap and the behavior when from/to are omitted. It does not clarify id format or whether the range is inclusive of both endpoints beyond the schema's wording.

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: 'Recompute the public record's hash chain server-side over [from, to]'. This is clearly distinct from sibling tools like muhabbit_record_entries and muhabbit_record_head, which read entries rather than re-derive and verify the chain.

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 usable invocation context: the default window when no bounds are supplied ('the latest 1000'), the hard cap, and that no credentials are needed. It does not explicitly contrast with sibling tools (e.g. when to verify versus when to just read entries), so it falls short of a 5.

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 genuinely new operational context: an authentication requirement with two credential forms (X-API-Key or Authorization: Bearer). It also discloses relevance ranking, which tells the agent results are ordered. It does not mention pagination or how limit interacts with ranking, but the auth disclosure is real value beyond the annotations.

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 waste, with the core capability front-loaded and the auth prerequisite appended compactly in parentheses. Nothing could be removed without losing 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 tool with three undocumented parameters, a domain enum, no output schema, and a large sibling set, the description is too thin. An agent still cannot tell what values 'vertical' accepts, how large a default result set is, or when to prefer this over the news/events tools.

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 all three parameters rest entirely on the description, which says nothing about 'query', 'limit' (1-50), or the 'vertical' enum (crypto/finance/tech/turkish). The word 'article corpus' loosely implies content scope but never explains that vertical narrows the corpus or that limit caps results.

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: 'Full-text search over the article corpus with relevance ranking.' An agent can distinguish it from aggregate siblings like muhabbit_sentiment_index or muhabbit_ticker_summary, but the description never names the closest alternative (muhabbit_news) to draw the boundary.

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 explicit when-to-use guidance and no exclusions. The closest thing is the implicit framing that this is for keyword lookup, which leaves the agent to infer how it differs from muhabbit_news or muhabbit_events.

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 and openWorldHint=false, so the safety profile is covered; the description adds genuinely new context beyond that, namely the required API key or wallet token transmitted as X-API-Key or Authorization: Bearer, and the fact that the index is derived from the trailing 24h of scored articles.

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 tight sentences with the metric, range, scope and time window front-loaded, followed by the auth prerequisite. Nothing is redundant or padded.

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 parameters, the description carries the burden of describing the return value and does so at a high level (0-100 overall plus per vertical). It stops short of saying how the per-vertical breakdown is shaped or how it is framed as a result, which is the only remaining gap for a no-arg read 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?

The tool takes zero parameters and the schema is empty, so there is nothing to disambiguate; the baseline for a parameterless tool is 4, and the description adds no conflicting 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 description names a specific metric (0-100 Fear & Greed index), its scope (overall and per vertical) and its computation window (last 24h of scored articles), so an agent knows exactly what it returns. It does not explicitly distinguish itself from the sibling muhabbit_sentiment_signals, but the defined resource is concrete enough to tell them apart.

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: an agent can infer this is the tool for a market-sentiment readout, but the description never says when to prefer it over muhabbit_sentiment_signals, muhabbit_confidence or muhabbit_ticker_summary, nor any exclusion conditions.

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 genuinely useful non-annotation context: that an X-API-Key or Bearer wallet token is required. It says nothing about response shape, pagination, latency, or whether all four signal families are always returned.

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, zero filler, with the capability stated up front and the auth note in parentheses. The noun-phrase style lacks a verb but is efficient and front-loaded.

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 read-only, single-filter tool this is close to adequate, but with no output schema the description should at least sketch what a 'signal' record looks like or how the four families are returned. Combined with the unaddressed `vertical` parameter, meaningful gaps remain.

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 one optional parameter at 0% schema description coverage, the description must carry the burden, and it never mentions the `vertical` filter at all. The schema's enum values (crypto/finance/tech/turkish) are somewhat self-explanatory, which keeps this from scoring lower, but the meaning of 'vertical' as a scope filter is never stated and 'vertical-shift' in the signal list could confuse an agent into conflating the two.

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 names the resource precisely, enumerating four signal families (momentum, volume-weighted, regime, vertical-shift), so the agent knows what data comes back. But there is no verb (list/fetch/compute) and no differentiation from the sibling muhabbit_sentiment_index, which sounds near-identical.

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?

No guidance on when to choose these signals over muhabbit_sentiment_index or muhabbit_confidence. The only usage instruction is an authentication prerequisite, which is helpful but is about access, not selection between alternatives.

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 and closed-world scope, and the description adds genuinely useful context beyond them: the paid-route requirement (API key, wallet token, or x402) and the limited coverage of only the most-mentioned assets. What is missing is what happens on an unsupported symbol (error vs empty), which matters for an agent retry strategy.

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 compact sentences with zero filler: the core operation comes first and the payment caveat follows in a parenthetical. Both sentences carry load an agent needs 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?

For a one-parameter read with no output schema, the description covers purpose, coverage limits, and payment/auth requirements. Only the return shape and unsupported-symbol behavior are left implicit, which is a minor gap at this complexity.

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 says the parameter is an asset symbol and hints at a supported set, but gives no format examples, casing rule, or explanation of the schema's pattern. That partially compensates, but not fully.

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: a 24-hour AI-generated news summary for a single asset symbol. The parenthetical about existing only for the most-mentioned assets meaningfully scopes the tool. It does not name or contrast siblings like muhabbit_news or muhabbit_recap, 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?

The description implies usage (per-symbol news synthesis) and adds a coverage caveat that tells the agent when the call may fail. However, it gives no explicit guidance on when to prefer this over muhabbit_news, muhabbit_recap, or the sentiment siblings, and no prerequisites for obtaining a supported symbol.

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