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

With no annotations provided, the description carries the full burden. It discloses the output (JSON of endpoints and MCP tools), the authentication mechanism (X-API-Key) and that the MCP process already has the key, plus the fact that no inputs are required. It does not explicitly state that the operation is read-only, but the tool name and 'read-only' phrasing strongly imply it, and no side effects are expected.

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 four short sentences with no fluff. It front-loads the purpose ('Discovery: JSON of...') and immediately follows with the when-to-use, auth, and input requirements. Every sentence earns its place; nothing is redundant or verbose.

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 zero-parameter discovery tool with no output schema, the description is fully sufficient. It covers what is returned (path + summary and tool names), when to invoke it, the auth context, and that no inputs are needed. An agent can call it without any further clarification.

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 and the schema coverage is trivially 100%. The description states 'No inputs,' which directly confirms this, aligning with the baseline of 4 for zero-parameter tools. It adds no confusion and succinctly communicates that no arguments are needed.

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

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

The description clearly states the tool's purpose: it returns a JSON catalog of all read-only HTTP APIs and the four MCP tools. The verb 'Discovery' and resource 'all OpenFolio read-only HTTP APIs' distinguish it from siblings like ro_holdings or ro_logs, which are specific data tools rather than a meta-catalog.

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 an explicit when-to-use instruction: 'Call this when unsure which RO endpoint exists.' This is direct and actionable. However, it does not explicitly mention when not to use it or name alternatives, though the siblings are implied as the actual data tools to use once a specific endpoint is identified.

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?

No annotations are provided, so the description bears the full burden of behavioral disclosure. It does disclose two genuine behavioral traits: the webhook_url is stripped from responses, and one grid's trades/chart are HTTP-only. However, it omits other traits an agent might need, such as response shape, ordering, or any pagination/limits — though for a zero-input listing tool this is a moderate, not severe, gap.

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 with no filler; the core purpose is front-loaded first, followed by use-cases and the sibling routing note. Each sentence earns its place, though the mixed-language use-cases (Chinese) add minor friction for English-reading agents.

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 no-input listing tool with no output schema, the description covers the essentials: what is returned (positions with performance), the data source, a data-hygiene caveat (webhook_url stripped), and the routing rule for deeper grid detail. It's reasonably complete given the tool's low complexity, though it stops short of describing the return format.

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 and schema coverage is trivially 100%, so the baseline of 4 applies. The description reinforces this by explicitly stating 'No inputs', which removes any doubt about invocation requirements. Nothing more is needed semantically since there are no parameters to document.

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 the resource precisely ('All %-grid positions with performance') and names the data source (GET /api/external/ro/grid), which clearly distinguishes it as the grid-position listing among siblings like ro_holdings and ro_logs. It lacks an explicit verb like 'List' or 'Fetch', but the phrasing strongly implies a read/listing operation, so intent is unambiguous.

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

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

Gives concrete trigger use-cases ('Use for 网格赚了没 / 哪些网格开着'), telling the agent exactly when this tool applies. It also states an explicit exclusion with a sibling pointer ('One grid's trades/chart are HTTP-only (see ro_catalog)'), which routes the agent away when it needs trade-level detail. Strong guidance, though it could be slightly more explicit about when NOT to use it in favor of ro_holdings/ro_logs.

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?

No annotations are provided, so the description carries the full burden. It indicates a GET operation and lists returned fields, implying a read-only data retrieval. However, it does not explicitly state that the operation is non-destructive, mention response structure (e.g., array vs object, grouped by broker), or discuss potential error conditions. The 'Current' qualifier and GET HTTP method provide some transparency, but more explicit disclosure would be better.

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 a single sentence that packs the endpoint, data fields, brokers, usage phrase, and a prerequisite note. It is concise and front-loads the core purpose. While it could be segmented for readability, it is efficient and free of fluff.

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's simplicity (no inputs), the description is largely complete. It lists the data fields returned and indicates broker scope. It does not specify the exact return format (e.g., JSON array) or any pagination, but for a no-input data retrieval tool, the agent likely has enough to invoke it correctly. The absence of an output schema increases the burden slightly, but the field list mitigates that.

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 input schema has zero parameters, and the description states 'No inputs.' Since there are no parameters to explain, the baseline of 4 applies. The description correctly notes the absence of inputs, which is all that is needed.

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 endpoint (GET /api/external/ro/holdings) and enumerates the returned fields (symbol, quantity, cost, market value, PnL) and brokers (Longbridge/Futu/IBKR). It clearly identifies what the tool does and is distinct from siblings like ro_catalog, ro_grid, ro_logs based on the holdings-specific focus.

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 an explicit usage trigger: 'Use for "现在仓位/持仓怎样"' (i.e., when users ask about current positions/holdings). It does not mention alternatives or exclusions, but the sibling names (catalog, grid, logs) make the differentiation clear. The note 'No credentials or webhooks' also clarifies prerequisites.

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?

With no annotations, the description carries the full burden for behavioral disclosure. It mentions default row limit (50), max (100), and substring search behavior, but does not cover auth requirements, response format, pagination beyond offset, or explicit read-only confirmation (though 'GET' implies it). This is adequate but not comprehensive.

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 with the endpoint and critical constraint front-loaded. Efficient overall, though the Chinese use-case phrase could be considered extraneous for a broader audience, but it does not dilute the core guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers calling constraints (filters, limits) but omits output/return format (no output schema), error behavior, and explicit pagination semantics. For a simple GET logs endpoint it is sufficient for making a correct call, but not fully complete for an agent that needs to interpret results.

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 baseline is 3. The description adds value by stating the mutual-exclusivity requirement (module OR search) and clarifying search is a substring on message/data, which goes beyond the schema's simple field descriptions.

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?

Description specifies a concrete action ('GET') on a clear resource ('logs'), names the endpoint, and gives a specific use case (查某某报错/最近日志). This distinguishes it from siblings (catalog, holdings, grid) which target different data domains.

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 states the mandatory condition ('Must pass module or search') and a negative condition ('Do not call with empty filters'). Also provides a usage context ('查某某报错/最近日志'), giving the agent clear guidance on when to invoke this tool.

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