Toolstem MCP Server

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

With no annotations provided, the description carries full burden. It discloses the tool returns derived rankings across specific dimensions, which is valuable behavioral context. However, it doesn't mention potential limitations like data freshness, rate limits, authentication requirements, or error conditions that would help an agent use it correctly.

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 appropriately sized and front-loaded with the core purpose. Every sentence adds value: the first defines the operation, the second specifies return values, and the third provides usage context. Minor improvement possible by tightening the financial metric list.

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 complexity (multi-company financial comparison), no annotations, but with output schema present, the description does well by specifying comparison dimensions and return rankings. It could be more complete by mentioning data sources or time periods, but the output schema likely covers return format details.

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 schema has 100% description coverage for the single parameter, so baseline is 3. The description adds value by clarifying the parameter represents '2-5 stock ticker symbols to compare' and implicitly reinforces the 2-5 company range, though this is already in the schema. It earns a 4 for reinforcing the parameter's purpose in context.

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 performs a 'side-by-side comparison of 2-5 companies' across specific financial dimensions, distinguishing it from siblings like get_company_metrics (single company metrics) or screen_stocks (filtering). It specifies the verb 'compare' and resource 'companies' with explicit 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?

The description explicitly states when to use this tool: 'for investment comparisons, competitive analysis, or evaluating alternatives in the same sector.' It distinguishes from siblings by focusing on multi-company comparison rather than single-company metrics or screening operations.

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