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 which attributes get compared, but says nothing about behavior for unknown slugs, whether the comparison is symmetric, or how the result is presented.

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 tight sentence with the resource front-loaded ('Side-by-side comparison of two brokers/tools') and the scope in a compact parenthetical. Nothing 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?

No output schema exists, but the parenthetical list of comparison dimensions effectively previews what the agent gets back, and both required params are documented. Minor gap: no handling notes for invalid or identical inputs.

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% — both a/b are documented as 'First/Second tool slug or name.' The description implies the two arguments are brokers/tools but adds no format, slug, or ambiguity-resolution detail beyond the schema, 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?

States a specific verb+resource: a side-by-side comparison of exactly two brokers/tools, and enumerates the dimensions compared (safety controls, paper trading, pricing, rate limits). It distinguishes itself implicitly from get_tool (single tool) by specifying two inputs, though it never names the sibling.

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 says what it compares but gives no guidance on when to choose it over get_tool (e.g. 'use get_tool for one tool, compare_brokers for two'). The 'two' arity hints at usage but no exclusions, prerequisites, or alternatives are stated.

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 the safe read-only and closed-world profile, so the bar is lower. The description adds valuable uncovered context by listing what the record contains (assets, live vs paper, approval/safety controls, pricing, rate limits, source, last-checked date) and signals data provenance/freshness, which goes 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?

A single dense sentence with the core purpose front-loaded and no filler. Every listed field contributes useful information about the return payload.

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 a fully documented single parameter, the description does the necessary work of enumerating return fields. It is largely complete, though it does not describe the response shape or behavior when the slug is unknown.

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 one parameter, and schema coverage is 100% with an example value ('alpaca-mcp-server') in the schema itself. The description adds no additional parameter meaning, so the baseline of 3 is appropriate when the schema fully documents the input.

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 clear verb+resource ('Full sourced record for one tool') and enumerates the record contents, so an agent knows this is a single-item detail lookup. It does not explicitly name the sibling it contrasts with (search_tools), but 'for one tool' implies the distinction.

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 singular scope: fetch details for one identified tool. There is no explicit when-to-use guidance, no statement of prerequisites, and no routing to alternatives such as search_tools or compare_brokers.

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 and openWorldHint=false, so the safety profile is covered. The description usefully adds that results include tool counts, but says nothing about ordering, pagination, or empty-state behavior, and there is no output schema to fall back on.

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 eight-word sentence with no filler, front-loading the action and the resource immediately. Nothing is 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?

For a no-argument listing tool with no output schema, the description conveys the essential return content (categories, each with a tool count). Ordering and pagination details are absent, but they are minor for a small taxonomy listing.

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. The description correctly implies no filtering or input is needed, and there is no schema surface left unaddressed.

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 (List) and resource (directory categories), plus the payload shape (with tool counts). It is clearly distinct from siblings like search_tools and get_tool, though it does not explicitly name or contrast them.

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: a zero-parameter enumeration tool named list_categories is self-evidently for browsing the category taxonomy. There is no explicit when-to-use statement, no mention of alternatives such as search_tools, and no 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety profile is covered. The description adds that results are short summaries, which is useful. However it doesn't mention pagination behavior beyond the schema's limit, or result ordering, so it adds only modestly beyond 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 tight sentences, front-loaded with the resource scope, with the routing to get_tool in the second. No 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?

Complete enough for a read-only search tool with annotations covering safety and schema covering two of three parameters. The absence of an output schema means the return format is only loosely described ('short summaries'), leaving some inference to 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?

Schema coverage is 67%; query and category are documented in the schema, and the description reinforces semantics by describing the return type but adds no new parameter detail. Baseline 3 is appropriate since the schema does most of the lifting.

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 a specific resource (the TradingAgentStack directory), and enumerates the content types it covers. An agent can immediately tell it apart from get_tool and list_categories.

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 alternative: 'use get_tool for full details', establishing the summary-vs-detail split. It also directs the category filter to list_categories. Clear when-to-use-this vs siblings.

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