BITHOT

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so safety is covered. The description still earns credit for disclosing that the content is editorially 'edited' (curated) rather than raw feed output, and that omitting the date yields the latest issue — both behavioral facts not in 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 filler, with the core action and the default behavior (latest) front-loaded before the routing hint. 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 read-only, single-optional-parameter tool with no output schema, this covers action, default behavior and selection context. It stops short of describing what the 'edited daily overview' actually contains (coverage window, sections), which would help an agent decide whether the result answers the user's request.

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 the date parameter and its omission semantics are already fully documented in the schema. The description's only addition is the word 'real' before YYYY-MM-DD, hinting at calendar validation, which is marginal over what the pattern and schema text provide.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get BITHOT's edited daily overview') and clarifies the scope as either the latest issue or an explicit YYYY-MM-DD date. It distinguishes itself conceptually from a 'raw chronological list', but never names which sibling (e.g. bithot_get_latest or bithot_search) supplies that raw list, so an agent must infer 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?

Gives a clear when-to-use condition: 'when the user asks for a daily report rather than a raw chronological list'. This is genuine routing guidance, though it points at a category of alternative rather than a named sibling tool, leaving the agent to map the alternative itself.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful non-annotation context: ranks are one-based and internal heat scores are deliberately excluded from the response, which prevents an agent from hunting for a field that does not exist.

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 zero filler; the primary retrieval purpose is front-loaded and the sibling routing and response caveat follow in priority order.

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-parameter, no-output-schema read tool, the description supplies the essential retrieval semantics (Top 10, one-based rank, heat scores omitted) and the routing to siblings. Only minor details such as the shape of each event entry are left unstated, which is acceptable 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?

Only one parameter and schema coverage is 100%, with the min/max/default fully documented in the schema. The description adds nothing about the limit parameter beyond the implicit 'Top 10' framing, so the 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?

The description states a specific verb and resource ('Get the current BITHOT Top 10') plus the returned detail (one-based rank), and explicitly contrasts with the sibling bithot_get_latest. An agent can distinguish this from the daily/weekly/monthly/chronological siblings without opening a 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 an explicit use case ('what is hot now') and a second one (discovering valid story public IDs), then names the alternative tool and the condition that selects it ('use bithot_get_latest for a chronological news list'). This is exactly the when/when-not/alternative pattern.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds only the mode-preference nuance (editorial picks vs. all public items), which largely duplicates the schema; it discloses nothing about result format or rate 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?

Three tight sentences with the core purpose front-loaded and usage/exclusion guidance following. No filler or repetition; every sentence carries weight.

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 list tool with a fully documented schema and annotations covering the safety profile, the description covers purpose, defaults, and exclusions adequately. No output schema exists, so return-value detail is not required, though a hint about what 'items' contain would round it out.

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 every parameter (mode, limit, window, category) is already fully documented in the schema. The description restates window ('24-hour or 7-day') and mode but adds no syntax or semantics beyond what the schema provides, making the baseline 3 correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Get the latest BITHOT items') and scopes it to 24h/7d briefings. It distinguishes itself from search and story/event tools by exclusion, though the 'latest... 24-hour or 7-day briefing' phrasing leaves some overlap with the daily and weekly siblings unresolved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly prescribes default behavior ('Prefer selected mode unless the user explicitly asks for every public item') and states when-not-to-use ('Do not use this for named-topic search or multi-source event context'). Strong, but it points to categories of alternatives rather than naming the specific sibling tools.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. Without an output schema, the description usefully discloses the shape of the result (monthly digest of key events grouped by section plus an overview), which is real added context 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 filler. The content scope is front-loaded and the usage/default rule follows immediately, with every clause carrying 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 read-only, single-optional-parameter tool with no output schema, the description covers purpose, scope, default behavior and the general return structure. It is nearly sufficient; only a hint about granularity, pagination or size limits is missing, which is minor here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'month' parameter is fully documented in the schema, including the YYYY-MM format and the omit-for-latest rule. The description's 'omit month for the latest' restates the schema rather than adding format or edge-case detail, so this is 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?

The description names a specific verb and resource ('Get BITHOT's edited monthly report') and characterizes the content precisely ('the month's most important events chosen from its dailies, grouped by section, with an overview'). The 'chosen from its dailies' phrasing also draws the boundary against the bithot_get_daily and bithot_get_weekly siblings without needing their schemas.

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 states when to use it ('for what happened this month or in a given month') and gives the default behavior ('omit month for the latest'), which is clear usage context. It stops short of explicitly naming alternatives such as bithot_get_weekly or bithot_get_daily as the fallback for non-monthly queries, so it is clear but not fully 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 declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds useful non-structured context: the four content areas returned and the ID-provenance constraint. It omits any mention of pagination behavior tied to report_limit or rate limits, so it stops short of 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?

Two sentences, zero filler, with the payload scope front-loaded and the ID constraint placed second where it is most actionable. Nothing repeats the schema verbatim.

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, and the description compensates by naming the four returned content areas plus the ID sourcing rule, which is what an agent needs to call it correctly. The only untouched item is how report_limit shapes the timeline output, which the schema already explains.

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 public_id and report_limit are fully documented in the schema, including the ID provenance rule the description repeats. The description adds no syntax or format detail beyond the schema, so the 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 verb (Get) and resource (one public story) and enumerates the payload areas: timeline, latest development, AI digest, related events. The 'one public story' scope implicitly separates it from feed-style siblings like bithot_get_latest or bithot_get_daily, but it never names those alternatives 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?

Gives a hard precondition and a prohibition: only pass a public_id from bithot_get_hot_topics links.story, never invent or infer IDs, and it names the sibling that supplies the ID. It does not, however, say when to prefer this tool over bithot_get_latest or bithot_search.

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, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds useful provenance context beyond that: the report is "edited" and curated from the dailies, and is grouped by section with an overview. It stops short of any auth/rate-limit or freshness caveats.

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 front-loaded sentences with no filler: the first defines what is returned, the second defines when to call it. Every clause earns its place.

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 burden of describing the return shape and does so (events grouped by section, overview). It could go slightly further on section granularity or format, but for a single optional-parameter read tool this is nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single optional `week` parameter is fully documented with its ISO pattern in the schema. The description only reinforces the default (omit = latest), adding no format or edge-case detail beyond the schema, so the 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?

Specific verb+resource ("Get BITHOT's edited weekly report") plus a concrete content model: the week's most important events chosen from its dailies, grouped by section, with an overview. This clearly separates it from the daily/monthly siblings.

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?

"Use this for what happened this week or in a given ISO week; omit week for the latest" gives clear when-to-use and default behavior. It does not explicitly state when to prefer bithot_get_daily or bithot_get_monthly, so sibling routing is implied rather than spelled out.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description earns credit beyond that by disclosing the non-obvious two-stage retrieval: editorial picks are searched first and the scope only expands to all public items when picks return 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?

Two dense sentences with zero filler; the scope and accepted query types are front-loaded, and the fallback behavior follows. 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 read-only search tool with no output schema and four well-documented parameters, the description covers scope, query domain, and the picks-then-expand behavior. It omits any mention of the category or limit parameters, leaving a small gap but nothing that would cause a mis-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 100%, so baseline is 3, but the description adds real semantic value the schema lacks: it enumerates the entity types q accepts (topic, company, model, product, person) rather than just restating the 2–200 character bound. It does not, however, add anything about category or limit 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?

States a specific verb ("Search") and resource ("BITHOT's latest 7 days") plus the accepted query types (topic, company, model, product, person). This clearly distinguishes it from the time-window retrieval siblings like bithot_get_latest and bithot_get_daily, though it never names those siblings 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 query-entity list implies when to reach for this tool (finding items about a subject), but there is no explicit when-to-use vs. when-to-use-a-sibling guidance or statement of prerequisites. Usage must be inferred from the verb and scope.

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