operant-mcp

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

Discloses specific return fields, error behavior for ambiguous names, and a crucial caveat about the comparison not indicating statistical significance. The readOnlyHint from annotations is consistent, and the description adds detailed behavioral context 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 well-structured sentences: first sentence states purpose and returns, second sentence provides usage caveat and error handling. No redundant information, every sentence adds value.

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 no output schema, the description fully covers what the tool does, what it returns, error conditions, and important limitations. It is self-contained and sufficient for an agent to understand and invoke the tool correctly.

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 already describes the parameters with 'Display name (or substring) of the first/second model.' The description only restates 'by display_name substring' without adding new semantics, and since schema coverage is 100%, a score of 3 is appropriate.

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: 'Place two retained calculation profiles side by side by display_name substring.' It specifies the exact fields returned and differentiates from sibling tools like get_case or list_cases by focusing on comparison.

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?

Provides guidance on ambiguous names (returns error listing all available display_names) and cautions that comparison_status=NOT_DURABLE means it's not evidence of outperformance. However, it does not explicitly state when to use this tool versus alternatives like get_results or list_cases.

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 mark readOnlyHint=true, so the description does not need to restate safety. The description adds useful behavioral details: what data is returned (full case with specific fields) and the distinction between axis 3 versus others. No contradictions with 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, front-loaded with the main action, and each sentence contributes essential information (what is returned, axis-specific key, and referral to sibling tool). 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?

Given the tool's simplicity, the description covers all necessary aspects: return content, key handling per axis, and a pointer to list_cases for browsing. Combined with schema and annotations, it is fully adequate for correct tool invocation.

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 context that for axis 3 the identifier field is 'id' instead of 'pair_id', but the schema only has a 'pair_id' parameter, creating a slight inconsistency. This adds some meaning but also potential confusion.

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 'Returns the full case' and lists specific components (prompts, decisions, rationale, bypass patterns). It distinguishes between axis 3 (using 'id') and axes 1/2/4 (using 'pair_id'), and differentiates from sibling tool list_cases.

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 advises when to use list_cases ('to browse available ids'), implying users should first retrieve valid identifiers. It does not explicitly list exclusion conditions but provides clear context for tool selection.

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 description adds meaningful behavioral context beyond the readOnlyHint annotation by detailing the returned content (axes, formula, labels, summary) and its source (baked case-file metadata). This helps the agent understand exactly what data to expect from a safe, read-only operation.

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 long, with the first sentence front-loading the most critical information (what is returned) and the second clarifying the data source. Every word earns its place, and there is no redundancy.

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 has no parameters, no output schema, and the description covers the key return components, it is largely complete. A minor gap is that it does not list the exact axis names, but this is acceptable for a summary description.

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?

With zero parameters, the baseline is 4. The description adds value by explaining the nature of the output, which compensates for the lack of parameter guidance.

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 returns the benchmark design, listing specific components like the 4 axes, OCS formula, decision labels, and scoring blocks. It distinguishes itself from sibling tools (get_case, get_results, compare_models, list_cases) by focusing solely on methodology rather than data or comparisons.

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?

While the description clarifies what the tool returns, it does not explicitly state when to use it versus alternatives (e.g., before analyzing results) or when not to use it. The context is clear but lacks comparative 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?

Beyond annotations (readOnlyHint=true, openWorldHint=false), the description explains that rows are not durable named-model performance claims and warns against misusing statistical measures. This adds valuable context about data limitations, though not all behavioral aspects are covered.

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, front-loaded with the action, and every sentence adds essential information without redundancy. No unnecessary 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?

Given no input parameters and no output schema, the description is adequately complete. It explains what is returned and provides critical usage warnings. Minor lack of detail on return format but sufficient for the tool's simplicity.

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 no parameters, so the description is not required to add param details. Baseline score of 4 is appropriate as the description does not need to compensate for missing schema info.

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 explicitly states the verb 'Return' and the resource 'retained model calculation profiles', listing specific fields. This clearly defines the tool's action and output, distinguishing it from siblings like 'compare_models' or 'get_case'.

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 clear guidance on appropriate use: returning calculation profiles without treating them as durable model evidence. It warns against ranking and misinterpreting stdev/significance. However, it does not explicitly contrast with siblings like 'compare_models' for when to prefer this tool.

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 provide readOnlyHint=true, and the description further explains that the tool returns only metadata, not full task prompts, and enumerates returned fields. No contradictions with 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, front-loads the core function, and includes no extraneous information. Every sentence adds value.

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 simple single-parameter tool with read-only annotations and a clear sibling relationship, the description fully covers the necessary context: what is returned, how to filter, and when to use an alternative.

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 context about omitting the axis parameter to get all cases, which is helpful but doesn't go beyond what the schema's enum and description already convey.

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 explicitly states the tool returns case metadata with specific fields (pair_id/id, axis, tier, grounding, side indicators), and distinguishes itself from get_case by noting it lacks full task prompts. The verb 'return' and resource 'cases' are clear.

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 explains when to use this tool (to get metadata) and when to use an alternative ('Use get_case to fetch a full case'). It also clarifies filtering by axis or omitting for all. However, it doesn't explicitly state when not to use it.

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