mitbbs.ai 华人空间 — Chinese News for AI Agents

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

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so safety is covered. The description adds real value beyond that: it names the ECB rate source and warns that TWD (despite being listed as supported) returns null, which prevents a silent misinterpretation. It stops short of describing rate freshness/timestamp or how cross rates are derived.

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 core action, followed by the value domain and the one caveat. Every clause carries information an agent needs; 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?

An output schema exists, so return shape need not be explained, and the description still flags the null case for TWD, which is the one output-related trap. What remains unstated is the rate timestamp/date basis and whether the default amount of 1 yields a straight rate lookup, both minor for a 3-parameter 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%, so the baseline would be 3, but the schema defines `from`/`to` as bare strings with zero enums. The description supplies the actual value domain (USD, CNY, EUR, JPY, GBP, CAD, AUD, HKD, TWD, KRW), which is meaning the schema does not carry at all.

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 ('Convert an amount between currencies') plus the rate source (ECB reference rates). No sibling tool in the list performs conversion, so the distinction is unambiguous, and the supported-currency list further pins down scope.

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 clear from the purpose and there is no competing sibling to route against, so no alternatives section is needed. It also sets a hard precondition by enumerating which currencies can be passed, which effectively tells the agent when the call is invalid.

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 readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered; the phrase "curated ... tracked by mitbbs.ai" is at least consistent with the closed-world hint. Beyond that the description adds no behavioral context: it doesn't say what happens when both q and id are supplied, whether q returns ranked or paginated results, or what a profile contains.

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, and the search-versus-profile fork is front-loaded immediately after the scope statement. 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?

An output schema exists, so return values need not be explained, and with annotations covering safety the remaining need is a scope statement plus invocation routing — both present. The only real omission is sibling differentiation, which is a minor gap for a simple read tool with no required parameters.

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%: q and id already carry descriptions that essentially mirror the prose, while type (an enum) and limit (1-20, default 10) are undocumented in both places. The description restates rather than extends the schema, so baseline 3 is appropriate given the partial coverage 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?

The description states a specific verb ("look up") and a clearly bounded resource ("curated entities ... tracked by mitbbs.ai"), and it enumerates the entity kinds so the agent knows the domain. It doesn't explicitly differentiate from the closest sibling, yellow_pages, which is a plausible source of confusion for a lookup-style 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 implies two distinct modes — pass q to search, or id (stable_id) for a profile — which is genuine routing guidance between invocation styles. However, it gives no guidance on when to reach for this tool versus yellow_pages or search_news, and no exclusion or prerequisite 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 destructiveHint=false, so the safety profile is covered. The description adds useful behavior beyond that: posts are paginated oldest first, and the response includes rights_basis and canonical url.

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, front-loaded with the core action and followed by the returned content. There is no unnecessary wording or 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?

The tool has an output schema and annotations that cover safety, and the description adequately states purpose and response shape. However, it omits usage guidance and leaves limit/offset semantics to a schema with low description coverage, so it is only minimally 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 only 33%, so the description should compensate for undocumented parameters. It mentions paginated posts and oldest-first ordering, which loosely relates to limit and offset, but it does not explain those parameters or their bounds and defaults.

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: 'Read a story thread', and adds that it returns topic metadata plus paginated posts. It is clear enough to distinguish from most siblings, though it does not explicitly name search_news or another alternative.

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 provides no explicit when-to-use guidance, prerequisites, or alternatives. The only hint is 'topic_id from search_news' in the schema, not in the description 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 readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is fully covered elsewhere. The description adds the meaningful qualifier "public" (only publicly visible boards are returned) but says nothing about pagination, result caps, or ordering of the returned list.

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 whose parenthetical is purely informative — the resource, scope, and returned fields all arrive immediately with zero 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 an output schema present, return values need no explanation, and annotations carry the safety profile; the description covers the resource and its scope. The remaining gap is pagination/result-size behavior for what could be a long board list, which matters slightly given how little the single optional param constrains 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?

Schema coverage is 100% and the single optional parameter (parent) is documented in the schema itself, so the baseline applies. The description adds no filtering semantics of its own — it never mentions that results can be narrowed by parent forum id.

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 pairs a specific verb and resource ("List public forum boards") and even enumerates the returned fields, so the operation is unmistakable. No sibling differentiation is offered, but none of the listed siblings (convert_currency, weather, visa_info, etc.) overlap with board listing, so that omission costs little.

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 by the verb "List" — there is no statement of when to call this versus another tool, no prerequisite, and no note about whether the call is scoped or full-enumeration. For a simple list endpoint that is acceptable, but nothing actively guides the 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?

Annotations already declare readOnlyHint=true, openWorldHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: a 15-minute data delay and a reference-only disclaimer, which affect how an agent should report and hedge the result. It stops short of describing behavior for unknown or ambiguous symbols (e.g. does 'USD_CNY' vs 'USD/CNY' resolve identically) or any rate limits.

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 front-loads what the tool accepts with concrete examples, the second delivers the two caveats an agent needs before relaying the number. Nothing is redundant and nothing could be cut 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?

With a single required parameter, an output schema, and full annotation coverage, the description carries the few things structured data cannot: asset-class breadth, accepted symbol forms, staleness, and the advice disclaimer. The only remaining gap is undefined behavior for invalid or ambiguous symbols, which is a minor omission for a read-only quote 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%, so the baseline is 3, but the description adds real meaning beyond the schema by showing both underscore and slash separators for forex and both ticker and full-name forms for crypto ('BTC or bitcoin'). That equivalence information is not present in the schema's terse 'Ticker (NVDA), pair (USD_CNY), or crypto (BTC)' line.

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 (unified market quote) and enumerates the three asset classes it covers with concrete symbol examples (NVDA, USD_CNY, BTC/bitcoin). It does not explicitly distinguish itself from the sibling convert_currency, which is the closest potential overlap for forex pairs, so an agent still has to infer that 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?

Usage is only implied through the example symbol formats; there is no explicit statement of when to use this versus convert_currency or a news/entity tool. The 'reference only, not investment advice' line sets a consumer-facing caveat but is not invocation 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is clear. The description adds that results are limited to guest-readable boards and lists returned fields, but it does not explain ranking, pagination, rate limits, or other search behavior 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?

The description is two sentences with the core purpose front-loaded and no wasted wording. The return-field list is compact and does not obscure the primary action.

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 search tool with annotations and an output schema, the description covers purpose, content domain, board scope, and expected result fields. It is not fully complete because it omits guidance on the limit parameter and does not mention how board ids relate to the list_boards sibling.

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%: q and board are documented, while limit is not described in the schema or description. The description adds domain context around Chinese-language news/forum content and guest-readable boards, which helps interpret board scope, but it does not clarify the limit parameter or explain how to obtain board ids.

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: search mitbbs.ai Chinese-language news headlines and forum posts. It also narrows scope to guest-readable boards, making the tool distinguishable from generic web search. It does not explicitly differentiate from siblings such as get_story or list_boards, so it falls 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 through the verb 'Search' and the content scope 'news headlines and forum posts.' The parenthetical 'guest-readable boards only' adds a constraint on where the search applies. However, it gives no explicit guidance on when to choose this tool over siblings like get_story or list_boards.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds behavior beyond that: the content set is finite and enumerated (10 cities, 8 countries, 3 local trips), which explains the closed-world hint, and it discloses the output language (Chinese) and audience. It does not state what happens when the destination is outside the covered 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?

A single dense sentence that front-loads the language, audience, and coverage; nothing is wasted. The trailing 'tips for Chinese travelers' slightly repeats the stated audience, keeping it from being maximally tight.

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 reference lookup with annotations and an output schema, the description supplies the essentials: what content comes back, in what language, and over what finite destination set. Minor gaps remain around whether one call covers a single destination and how unsupported destinations behave, which the dest slug example only partially covers.

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%: dest has a slug description with a mapping example, while cat is an undescribed enum. The description's enumeration of '10 US cities, 8 countries/regions, 3 NYC day trips' is useful because it obliquely maps to the cat values city/country/local, but that mapping is left implicit and neither parameter is discussed directly, so only modest meaning is added.

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 (Chinese-language travel guides) and enumerates the exact content scope: 10 US cities, 8 countries/regions, 3 NYC day trips, plus the sections returned (overview, sights, food, transport, season, tips). It implicitly separates the tool from siblings like visa_info and weather by being content coverage rather than practicalities, though it never explicitly states 'returns guide content for a destination' as a verb.

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 coverage list and the phrase 'tips for Chinese travelers', so an agent can infer this is the right tool for destination overview content. However, there is no explicit when-to-use statement, no mention of the sibling tools it should be preferred over (visa_info, weather) for overlapping travel questions, and no guidance on the cat parameter for choosing between city, country, and local 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 already cover the safety profile (readOnly, non-destructive, closed-world), and the description usefully adds that output is in Chinese and includes Visa Bulletin priority dates, plus a non-legal-advice caveat. It does not disclose whether the underlying policy data is periodically refreshed, which matters for a tool whose value depends on currency of Visa Bulletin dates.

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 with no waste: domain and coverage are front-loaded, and the safety caveat is placed at the end where it belongs. 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?

For a single-optional-param reference tool with an output schema, the description supplies the two things the schema cannot: output language (Chinese) and the not-legal-advice caveat. The main remaining gap is data recency/refresh cadence, which is material for monthly Visa Bulletin figures.

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 the single parameter already documents itself ("Visa category; omit for the full hub") with a full enum. The description's category list largely restates the enum, adding no syntax, default, or edge-case meaning beyond what the schema provides, so 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 names a specific resource domain (US visa/immigration policy) and enumerates the covered categories (F-1, H-1B, EB-1/2/3/5, family, N-400) plus Visa Bulletin priority dates, so an agent knows exactly what content it returns. It stops short of a crisp retrieval verb ("Returns/Retrieves"), reading more like a content label, but the scope 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?

"Reference only — not legal advice" sets a clear boundary on how results may be used, which is genuine usage guidance. However, there is no statement of when to call it (e.g., policy/compliance questions about US immigration), no note on whether omitting `type` is the right default for broad questions, and no alternatives to compare against — the siblings are unrelated domains.

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 establish this operation as read-only, open-world, and non-destructive, so the description does not need to restate safety. The description does add useful context beyond those annotations: the upstream data source, Open-Meteo, and its CC-BY 4.0 license, which implies an attribution obligation. It does not state units (metric vs imperial), the language of the output, or the freshness or caching of the weather data.

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?

This is one compact sentence that leads with the core capability and then gives provenance, with no filler. Every clause carries information the agent would otherwise be missing.

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-only tool with an output schema that documents return values, the description covers scope, bilingual city support, and data provenance. The remaining gap is the zero-required-parameter behavior: the description never states what the tool returns if no city is supplied, and it does not state units.

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 the single city parameter is fully enumerated with slugs, so the schema already carries almost all of the documented meaning. The description reinforces the intent of that parameter by mentioning '16 cities (Chinese + English)', but it adds no format or resolution rules beyond what the schema documents, and it does not explain what happens when the parameter is omitted even though the parameter is not required. 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 names the specific resource and scope: 'Current weather + 7-day forecast for 16 cities', and adds that city names come in Chinese and English. An agent immediately knows this is a weather-reporting tool, though it does not explicitly differentiate itself from any sibling (none of the siblings are weather-related, so the need is lower).

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 phrase 'current weather + 7-day forecast' and by the fixed list of 16 cities, which tells the agent the tool is limited to those locations. However, there is no explicit statement about when to use this tool rather than other tools or other sources, and no guidance on how to handle requests outside the city list.

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 a safe, closed-world read. The description adds genuinely useful context beyond them: the dataset is NYC-scoped, finite (4,389+ listings), and Chinese-language oriented. It does not disclose pagination behavior or how many results are reachable via page/limit, so the added value is moderate rather than rich.

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 with the scope and the two search modes; nothing is wasted or 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?

With an output schema and safety annotations present, the description needn't explain return values. However, for a paginated search tool it leaves pagination semantics and the q/cat interaction undescribed, which are the main remaining unknowns.

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%: q and cat are documented in the schema, while page and limit have no descriptions anywhere. The description reinforces that searching is by keyword or category but says nothing about pagination depth, the 50-result limit, or defaults, so it does not compensate for the 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?

The description gives a specific verb and resource ('Search ... NYC Chinese business listings') plus the two search axes (keyword or category) and a dataset size, so the agent knows exactly what domain this covers. No sibling tool (weather, visa_info, market_quote, etc.) overlaps, so explicit differentiation isn't needed, but it also isn't 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?

'by keyword or category' hints at which parameter to use, but there is no guidance on when to pick this tool over doing something else, no prerequisites, and no note on whether keyword and category can be combined or which wins.

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