YieldLord · 包租公

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

Annotations only declare readOnly=false, idempotent=true, destructive=false, openWorld=false; the description goes well beyond that by disclosing the no-arg return shape (text and URL only), the one-shot token semantics of pickup, the mandatory user-confirmation requirement for start_trial ('Never confirm on the user's behalf'), and the OAuth mechanics (HTTP 401 + WWW-Authenticate, dynamic client registration, PKCE S256, public client, redirect_uri handling). It also tells the agent to re-list tools after connecting, which is a behavioral consequence no annotation conveys.

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 status purpose is front-loaded in the first sentence and almost every sentence carries non-redundant routing or flow information. It is nonetheless a dense single paragraph where the connection-mode instructions are stacked ('Call this when... Call it again with... Call it again right after'), which costs readability versus a mode-by-mode 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 six-parameter, no-output-schema tool that spans status reporting and three distinct authorization paths, the description covers triggers, per-mode preconditions, return shapes ('returns text and a URL only', 'returns pending until the user approves, then the access token'), safety rails, and post-connect follow-up. Nothing an agent needs in order to select a mode and call it correctly 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 the baseline is 3; the description earns above baseline by tying parameters into an execution order the schema does not spell out (start_link then pickup, start_trial then confirm, re-call after sign-in). It does not, however, add format or validation detail beyond what the per-parameter schema text 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?

The description names the exact resource and fields it reports (connection state, tier, remaining credits, Gold trial-vs-paid and end date) and separately names each action mode (start_authorization, start_link, start_trial, pickup, confirm). An agent can tell immediately that this is the account-connection/status tool and that it does not overlap with the market- or option-oriented siblings. The compound status-plus-flow nature is disambiguated by mode rather than left vague.

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 ('am I connected', 'how many credits do I have left') plus a second condition: when the user asks about THEIR OWN positions, portfolio, morning brief or realized history, since anonymous access cannot see those. It also states preconditions for each mode ('only after the user has an account', 'connected free accounts only' for the trial) and which mode to pick when the agent cannot receive a browser redirect.

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 indicate readOnly and openWorld, but the description adds substantial behavioral context: it prices and scores the exact contract, returns live quote, Greeks, premium, collateral, yield, expiration probability from the seller's side, and RENT score. It also explicitly says that if pricing fails it will say so and why, rather than substituting another contract, and that the output is analysis, not a recommendation.

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 dense but well-structured: purpose first, then differentiation, then return contents, then failure behavior, then a caveat. Every sentence adds distinct value and there is no filler or repetition of schema fields.

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 no output schema and only 29% schema description coverage, the description is unusually complete. It covers what the tool returns, how it behaves on failure, and how to interpret the output (analysis, not a trade recommendation). The only minor omission is context for lang/risk, but their enum values are mostly self-explanatory.

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 carries real weight. It correctly maps the four required parameters to a concrete contract and adds meaning for strike ('including strikes the screener would never surface'). However, it does not describe the optional lang and risk parameters, leaving their semantics to the schema's enum values.

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 opens with a specific verb and resource: 'Explain ONE specific option contract the user named' and enumerates the contract components (ticker, put/call, strike, expiry). It also explicitly contrasts with explain_score and compare_candidates, so an agent can immediately tell this tool apart from alternatives.

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 clearly states when to use this tool: when the user names an exact contract, including strikes the screener would not surface. It names the alternatives and explains their limitation ('can only explain contracts the engine already picked'), which gives the agent a concrete routing rule.

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

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

Beyond the readOnlyHint and openWorldHint annotations, the description adds meaningful behavioral context: it is not advice, it returns candidates/analysis, and the defined_risk default is not silent — 'the result says which was used and why.' This is strong disclosure of behavior beyond what annotations provide.

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 no filler: the core purpose and disclaimer come first, followed by the critical defined_risk usage caveat. Every clause contributes information needed to use the tool correctly.

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 7-parameter tool with no output schema, the description covers the most important decisions and behavioral caveats. It could be more complete by explaining risk/intent selections and what the returned analysis contains, but the core invocation with just ticker is clear and safe.

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 43%, and the description substantially compensates for the most nuanced parameter, defined_risk, including the default behavior. However, it does not explain risk, intent, or direction beyond their enum names, and the 'RENT' ranking concept is left undefined, so the compensation is only partial.

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

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

The description uses a specific verb and resource: 'Find RENT-ranked option income candidates' for a ticker. It actively disambiguates the tool name by stating 'candidates only, not advice' and 'Output is analysis, not a recommendation to trade,' making its purpose unmistakable.

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 explicit guidance for the key decision: 'Set defined_risk=true for CREDIT SPREADS ... instead of single-leg naked selling; omit it and we default to whatever this user actually trades.' It clearly explains the main branch of use, though it does not explicitly name alternative tools or state when not to use the tool at all.

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. The description adds the meaningful clarification that the output is analysis, not a trade recommendation, and characterizes it as a 'current' snapshot. This goes beyond the annotations without contradicting them.

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 that conveys the core purpose and a key behavioral caveat with no wasted words. Efficient and easily parseable.

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 tool with safety annotations covering read-only and open-world behavior, the description is sufficient. It communicates what the tool outputs and the important non-recommendation aspect. No critical information is missing.

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

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

The tool has zero parameters, so the schema is fully covered. The description does not need to explain parameters. Baseline of 4 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 clearly states the tool's purpose: providing a current market climate analysis based on market regime, VIX/IV environment, and macro proximity, with output as a seller-friendliness read. It is specific and distinct from siblings like find_recommendations, though it does not explicitly name alternatives.

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 for market climate analysis but does not explicitly state when to use this tool versus alternatives. It does clarify that the output is not a trade recommendation, indirectly guiding away from tools like find_recommendations, but lacks direct when/when-not guidance.

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