Marketgenius

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

With no annotations provided, the description carries the full burden. It successfully discloses that this opens a React MCP App UI (not a silent calculation), mandates user interaction before invocation ('ask first'), and supports both empty and pre-filled parameter modes. Minor gap: does not describe what happens after opening (return values, user interaction flow, or lifecycle).

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?

Appropriately structured as procedural logic with clear IF/THEN branches. Front-loaded with the core action. The ALL CAPS emphasis and 'STOP' directive are slightly verbose but necessary for preventing silent invocation errors. Every sentence serves a specific purpose in guiding correct tool invocation.

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 this is a UI-opening tool with four optional parameters and no output schema, the description adequately covers the critical invocation protocol (ask-first requirement, conditional parameter passing). It appropriately omits detailed return value explanations (no output schema exists), though it could benefit from brief context on how this tool relates to its _state/_update siblings in the interaction flow.

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%, documenting all four parameters (years, beginningValue, endingValue, currencySymbol) with types, defaults, and descriptions. The description adds procedural context about when to provide parameters (only for pre-fill scenarios) but does not add semantic meaning beyond what the schema already provides, warranting the baseline score for high-coverage schemas.

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 it 'Open[s] the CAGR Calculator React MCP App UI' — specific verb (open) + resource (CAGR Calculator UI). It distinguishes itself from siblings (cagr_state, cagr_sync, cagr_update) by identifying as the primary UI entry point rather than a state management or synchronization utility.

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 exceptional explicit guidance: 'ALWAYS ask first — never call this tool silently' with the exact question to pose to users. Offers clear conditional branches: 'IF directly → call this tool now with no params' versus 'IF pre-fill → collect only the input schema fields,' including the critical constraint 'do not guess or invent field names.'

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 provided, the description carries the full burden of behavioral disclosure. It successfully adds critical context about GUI manual edits affecting state and explicitly prohibits looping behavior. However, it omits details about return value structure or session lifecycle management.

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 consists of three tightly constructed sentences that are front-loaded with purpose and progress logically through usage context to constraints. Every sentence earns its place with no redundant or tautological language.

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?

While the description adequately covers the primary use case and GUI interaction context, it has clear gaps given the lack of output schema and zero schema coverage for the input parameter. It does not describe the return value format or provide parameter documentation, which are needed for complete agent understanding.

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 0% description coverage for the required 'sessionId' parameter. The description mentions an 'open CAGR Calculator' implying a session context, but fails to explicitly document what the sessionId parameter represents or how to obtain it, leaving a significant documentation gap.

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 'Read[s] the current field values of the open CAGR Calculator,' providing a specific verb and resource. It clearly distinguishes this read-only state inspector from sibling tools like 'update' and 'sync' variants through its naming and description.

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 explicit when-to-use guidance ('Call this before answering any question about the current values') and warns about stale data scenarios ('the user may have changed fields manually in the GUI'). It also includes clear negative constraints ('Do not call this on a loop; call it once on demand').

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 provided, the description carries the full burden. It discloses the write destination (session store), the caller constraint (View-only, hidden from model), and the integration pattern (enables state tool reads). Lacks details on idempotency or error states, but covers the essential architectural behavior.

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, zero waste. First sentence front-loads the action and purpose (sync to session store for model access); second sentence provides usage context (View caller, hidden from model). Every word earns its place with 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 no output schema and 100% input schema coverage, description adequately covers the sync pattern and session flow. Explains the 'why' (so model can read via state tool) and 'who' (View). Could benefit from noting if the call returns confirmation or is fire-and-forget, but sufficient for tool selection.

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%, establishing baseline 3. Description refers collectively to 'user-entered field values' which maps to the calculator inputs (years, beginningValue, endingValue, currencySymbol), adding categorical context but no additional format constraints or validation rules beyond the schema.

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 uses specific verb 'Sync' with resource 'user-entered field values of the open CAGR Calculator' and destination 'session store.' Explicitly distinguishes from sibling mg_calculator_cagr_state by stating this tool enables the model to 'read them via the state tool,' clarifying this writes while the state tool reads.

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 when to use ('after any field change'), who should use it ('Called by the View'), and critical exclusion ('hidden from the model'). Clearly indicates the alternative path for the model (use state tool to read), preventing incorrect invocations by the AI agent.

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, description carries full burden. Discloses critical behavioral traits: versioning requirement (must pass current version), partial update semantics ('omit all others'), last-write-wins behavior ('only the last one applies'), and GUI state interaction. Lacks only return value/error description.

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?

Four sentences, zero waste. Front-loaded with purpose, followed by prerequisites, parameter sourcing, and batching constraints. Every sentence contains actionable instruction.

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 stateful update tool with versioning, description is comprehensive: covers lifecycle (state→update), concurrency control, and partial update patterns. No output schema exists; description adequately compensates by explaining behavioral outcomes.

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% (baseline 3). Description adds crucial workflow context: version must come from mg_calculator_cagr_state call, and optional fields should be omitted for partial updates—semantics not obvious from schema alone.

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?

Clear specific verb ('Update') + resource ('fields in the already-open CAGR Calculator'). Distinguishes from siblings by referencing 'already-open' state and explicitly naming mg_calculator_cagr_state prerequisite.

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?

Exceptional guidance: explicit prerequisite ('ALWAYS call mg_calculator_cagr_state first'), rationale ('user may have changed values manually'), alternative sourcing ('or from the open tool'), and batching requirements ('Send all changes in a single call').

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 provided, so description carries full burden. It discloses that this opens a UI (not a silent calculation) and requires user interaction, but lacks details on what 'opening' returns (URL? component? JSON?), side effects, or auth requirements. The procedural transparency is good but functional transparency is incomplete.

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?

Well-structured with clear IF/THEN branching for the two invocation paths. However, uses aggressive ALL CAPS for emphasis ('ALWAYS', 'STOP') which reduces readability slightly, and the procedural instructions are lengthy (though necessary given the 19-parameter complexity).

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 19 parameters with conditional logic, the description adequately covers input handling patterns. However, with no output schema provided, the description fails to explain what the tool returns (calculation results? UI URL? success boolean?), leaving a significant gap in understanding the tool's complete contract.

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 100% schema coverage, baseline is 3. The description adds crucial semantic context about the dual-mode architecture: instructing to ask 'By amount invested or by number of shares?' and collect only fields 'matching that mode', clarifying the ba- vs bs- prefix convention in the schema.

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 it 'Open[s] the Dividend Calculator React MCP App UI'—specific verb and resource distinguish it from calculation-computation tools. However, it does not explicitly differentiate from sibling tools like 'mg_calculator_dividend_state' or 'mg_calculator_dividend_update', leaving ambiguity about which dividend tool to use when.

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 explicit conditional workflow: 'ALWAYS ask first — never call this tool silently', then branching logic for 'directly' (no params) vs 'pre-fill' (collect mode-specific fields). Explicitly warns 'do not guess or invent field names', addressing a real risk with 19 optional parameters.

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 provided, the description carries the full burden. It discloses the read-only nature and performance characteristics (looping warning), but lacks details on error handling, return format, or session lifecycle since no output schema or annotations exist to supplement it.

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 sentences with zero waste: first establishes purpose, second provides usage context, third gives behavioral constraints. Information is front-loaded and each sentence earns its place.

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 single-parameter tool with no annotations or output schema, the description adequately covers the workflow intent but leaves critical gaps: the sessionId parameter is undocumented and the return value (field data) is not described, though the absence of an output schema reduces the burden for return value 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?

Schema description coverage is 0% for the single required 'sessionId' parameter, and the description fails to compensate by explaining what this parameter represents, where to obtain it, or its relationship to the 'open Dividend Calculator' mentioned.

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 ('Read') and resource ('current field values of the open Dividend Calculator'), clearly distinguishing this state reader from its siblings (dividend_update, dividend_sync, etc.) which imply mutation or synchronization operations.

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 explicit when-to-use ('Call this before answering any question about the current values'), explains the prerequisite context ('user may have changed fields manually in the GUI'), and explicitly warns against anti-patterns ('Do not call this on a loop').

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 provided, so description carries full burden. Discloses key behavioral traits: writes to 'session store', functions as persistence layer between View and Model, and is idempotent/sync-oriented. Explains data flow (View→session store→Model via state tool) which is critical architectural context for a plumbing tool.

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, zero waste. First sentence delivers purpose and mechanism; second delivers usage context and architectural constraints. Front-loaded with essential information distinguishing it from sibling tools.

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?

Adequate for a complex 20-parameter sync tool with no output schema. Explains the View-Model architectural pattern and session persistence behavior. Could be improved by explicitly noting the 'amount' vs 'shares' mode distinction that explains the parameter prefixes (ba/bs), though this is derivable from schema descriptions.

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 has 100% description coverage (all 20 parameters documented), establishing baseline of 3. Description adds conceptual context that parameters represent 'user-entered field values' from a UI, but does not elaborate on the dual-mode parameter grouping (ba* vs bs* prefixes) or inter-parameter relationships beyond schema definitions.

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 uses specific verb 'Sync' with clear resource ('user-entered field values of the open Dividend Calculator') and destination ('session store'). Explicitly distinguishes from siblings by specifying this is for the Dividend Calculator (vs cagr/market_cap variants) and contrasting with 'state tool' (read) vs this tool (write).

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 when to call ('after any field change'), who calls it ('Called by the View'), and visibility ('hidden from the model'). Implies the alternative workflow ('so the model can read them via the state tool'), though it could explicitly name the sibling 'dividend_state' tool for clarity.

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 provided, the description carries the full burden of behavioral disclosure. It successfully explains the optimistic locking pattern (version parameter requirement), the partial update semantics (PATCH-like behavior), and the GUI synchronization constraints. It does not describe error handling or return values, but covers the critical stateful behavior thoroughly.

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?

Four sentences with zero waste: sentence 1 states purpose, sentence 2 gives the mandatory prerequisite, sentence 3 explains the partial field update pattern, and sentence 4 warns about batching behavior. Information is front-loaded and logically sequenced.

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 complex stateful tool with 21 parameters, no annotations, and no output schema, the description successfully establishes the complete workflow (state → update) and concurrency control requirements. It could be improved by mentioning success indicators or error conditions, but it covers the essential integration pattern comprehensively.

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?

While the schema has 100% coverage (baseline 3), the description adds crucial semantic context about the partial update pattern ('Only pass the fields the user explicitly asked to change; omit all others'), which is essential for correctly using this 21-parameter tool without overwriting unspecified fields.

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 ('Update') and resource ('fields in the already-open Dividend Calculator'), clearly distinguishing this as the mutation tool for an existing session versus sibling tools like mg_calculator_dividend (open) or mg_calculator_dividend_state (read).

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 explicit prerequisites ('ALWAYS call mg_calculator_dividend_state first'), explains the rationale ('user may have changed values manually'), names the specific alternative tool, and warns against anti-patterns ('multiple sequential calls lose intermediate updates').

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 provided, the description carries the full burden and succeeds well: it discloses that this opens a UI (not a silent calculation), requires user interaction ('ask first'), and has specific conversational pre-conditions. It could improve by mentioning the relationship to state/sync/update siblings or persistence behavior, but the interactive workflow is thoroughly documented.

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 uses clear structural formatting with IF/THEN branching and strategic capitalization (ALWAYS, STOP) for emphasis. While slightly verbose with imperative commands, every sentence serves a specific instructional purpose. The front-loading of the consent requirement ('ALWAYS ask first') is appropriately prioritized.

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 this is a UI-opening tool with no output schema, the description appropriately focuses on interaction workflow rather than return values. It adequately covers the 4 parameters and their conditional usage. It could briefly acknowledge the existence of state/sync/update sibling variants, but the description is sufficient for correct invocation of this specific tool.

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 has 100% coverage (baseline 3), but the description adds valuable workflow context by specifying which fields to collect for pre-fill mode ('share price and shares outstanding') and explicitly warning 'do not guess or invent field names'. This adds semantic meaning about when and how to use parameters beyond the schema definitions.

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 'Open[s] the Market Cap Calculator React MCP App UI' with specific verb and resource. It distinguishes from sibling calculators (CAGR, Dividend, Profit Margin) by specifying 'Market Cap'. However, it focuses heavily on the UI-opening mechanism rather than the calculation purpose, and 'React MCP App UI' adds implementation jargon without clarifying the mathematical function.

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?

Exceptional workflow guidance with explicit branching logic: 'ALWAYS ask first — never call this tool silently', specific questions to ask the user ('Open directly, or pre-fill...'), and clear instructions for both modes (direct → no params, pre-fill → collect specific fields). This provides clear when-to-use guidance for parameters versus parameterless invocation.

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 provided, the description carries the full burden and adds valuable behavioral context about GUI staleness ('user may have changed fields manually') and usage patterns (anti-looping). Lacks description of return values or error conditions, which is notable given no output schema exists.

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 well-structured sentences that are front-loaded with purpose, followed by usage context, and ending with operational constraints. Every sentence earns its place with zero 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?

For a single-parameter read tool, the description adequately covers operational context and usage timing. However, given the lack of output schema, it should ideally describe the structure of the returned field values to be fully complete.

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 0% with no parameter descriptions. The description implies the session context ('open Market Cap Calculator') but does not explicitly define what the 'sessionId' parameter represents or how to obtain it, offering only implicit guidance rather than explicit documentation.

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 action ('Read') and resource ('current field values of the open Market Cap Calculator'), clearly distinguishing it from sibling tools like mg_calculator_market_cap_update or mg_calculator_market_cap_sync through the specific 'read' verb and 'state' context.

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 explicit when-to-use ('Call this before answering any question about the current values') and when-not-to-use ('Do not call this on a loop; call it once on demand'), including the critical context that 'the user may have changed fields manually in the GUI'.

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 provided, the description carries the full burden and successfully discloses the caller pattern (View vs. Model), the data flow (user input → session store), and the relationship to the state tool. It lacks explicit mention of idempotency, validation behavior, or error handling, preventing a perfect score.

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 zero waste. The first sentence establishes purpose and mechanism; the second establishes invocation pattern and audience. Information is front-loaded and every clause earns its place.

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 moderate complexity (5 simple parameters, no output schema, no annotations), the description is complete. It explains the architectural role, the data flow between View and Model, and references the session management pattern ('returned by the open tool') without needing to repeat parameter details already well-covered in the schema.

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%, establishing a baseline of 3. The description adds valuable context beyond the schema by characterizing the parameters as 'user-entered field values' and placing them in the context of an 'open Market Cap Calculator' and 'session store,' helping agents understand the data provenance and lifecycle.

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 synchronizes 'user-entered field values of the open Market Cap Calculator back to the session store,' using specific verbs (sync) and identifying the resource (field values). It effectively distinguishes this tool from its siblings by explicitly noting the model should use the 'state tool' to read values, while this tool is for writing/syncing.

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 explicit usage timing ('Called by the View after any field change'), audience restriction ('hidden from the model'), and directs to the correct alternative ('so the model can read them via the state tool'). This creates a clear architectural map of when to use this sync tool versus the state 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?

With no annotations provided, the description fully discloses critical behavioral traits: optimistic locking via version parameter, partial update semantics (omit unchanged fields), destructive batch behavior (only last call applies), and GUI synchronization requirements.

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?

Four dense sentences with zero waste: opens with the action, follows with prerequisite and rationale, then parameter handling, and closes with batching warning. Critical constraints are front-loaded and emphatic (ALWAYS, only, single call).

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 stateful nature of the tool and lack of annotations/output schema, the description comprehensively covers the concurrency model, prerequisite workflow, partial update semantics, and side effects necessary for safe 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?

While schema coverage is 100% (baseline 3), the description adds crucial workflow context: it specifies that version comes from the state call and establishes the partial update pattern (only pass explicitly changed fields), significantly aiding correct parameter population.

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 specific action (update fields) and target resource (already-open Market Cap Calculator), distinguishing it from sibling tools like the 'open' and 'state' variants by emphasizing it operates on an existing session.

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?

Excellent explicit guidance: mandates calling mg_calculator_market_cap_state first to avoid overwriting manual GUI changes, specifies to only pass explicitly requested fields for partial updates, and warns against multiple sequential calls due to intermediate update loss.

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 provided, the description carries the full burden and effectively discloses the interactive nature requiring user confirmation before invocation. It details the two operational modes (direct open vs pre-filled) and the requirement to 'STOP' after direct invocation. Does not mention persistence or side effects, but covers the critical interaction protocol.

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?

Front-loaded with the core action. Uses structured IF/THEN logic and capitalization effectively to emphasize critical workflow constraints ('ALWAYS', 'STOP'). Slightly verbose formatting with newlines, but every sentence serves the essential purpose of guiding the interaction protocol.

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 interactive UI nature and lack of output schema, the description appropriately focuses on the invocation workflow rather than return values. It covers the essential interaction pattern and parameter strategy. Could mention what the calculator computes (profit margin formula) for completeness, but the tool name makes this evident.

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%, establishing a baseline of 3. The description adds value by specifying which parameters to use in which mode (revenue and cost for pre-fill) and explicitly warning not to 'guess or invent field names.' This usage context beyond raw schema definitions warrants a 4.

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?

Clearly states the tool opens the 'Profit Margin Calculator React MCP App UI' with specific verb and resource. However, it does not explicitly differentiate from the sibling state/sync/update variants (e.g., mg_calculator_profit_margin_state), though the 'React MCP App UI' phrase implicitly distinguishes this as the main UI opener.

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 explicit workflow guidance: 'ALWAYS ask first — never call this tool silently' with the exact question to ask. Includes clear branching logic for 'direct' vs 'pre-fill' modes, specifying when to call with no params versus when to collect specific inputs. This is exemplary usage 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?

With no annotations provided, the description carries the full burden. It successfully discloses GUI interaction patterns (manual user changes), read-only nature (implied by 'Read'), and usage constraints (no looping). Deducted one point for not clarifying error behavior if no calculator is open.

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 sentences with zero waste: sentence 1 defines the action, sentence 2 provides usage context and rationale, sentence 3 gives frequency constraints. Information is front-loaded and every sentence earns its place.

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 single-parameter tool without output schema, the description adequately covers operational context and usage patterns. However, the complete absence of parameter documentation (given 0% schema coverage) and lack of return value hints leave critical gaps for agent 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?

The schema has 0% description coverage for the 'sessionId' parameter, and the description fails to compensate by explaining what sessionId represents or how to obtain it. While 'open Profit Margin Calculator' implies a session context exists, the parameter itself is completely undocumented.

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 'Read the current field values of the open Profit Margin Calculator,' providing a specific verb (Read) and resource (field values). The '_state' suffix and mention of 'current field values' clearly distinguishes this from sibling update/sync/calculation tools.

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?

Excellent guidance: 'Call this before answering any question about the current values' specifies when to use, 'the user may have changed fields manually in the GUI' explains the prerequisite context, and 'Do not call this on a loop; call it once on demand' explicitly prohibits anti-patterns.

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 provided, so description carries full burden. Explains the write-to-session-store side effect, the View/Model separation pattern, and visibility constraints. Lacks error handling or idempotency details, but covers the primary behavioral contract.

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 zero waste. First sentence establishes purpose and mechanism; second provides critical usage constraints. Front-loaded with essential information.

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?

Adequate for a 4-parameter sync tool with no output schema. Explains the session-based architecture and the relationship to the state tool. Could mention required session initialization or error cases, but sufficient for correct 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 has 100% coverage (baseline 3). Description adds value by contextualizing parameters as 'user-entered field values of the open Profit Margin Calculator' rather than isolated inputs, clarifying they belong to a specific calculator session.

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?

Specific verb ('Sync') + resource ('user-entered field values of the open Profit Margin Calculator') + destination ('session store'). Distinguishes from siblings by specifying this is the sync variant that pushes data for later reading via the state tool.

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 when-to-use ('Called by the View after any field change'), explicit exclusion ('hidden from the model'), and explicit alternative ('model can read them via the state tool'). Perfect architectural 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?

With no annotations provided, the description carries full burden and excels: it discloses optimistic locking (version parameter requirement), warns about GUI synchronization conflicts, and explains that sequential calls lose intermediate updates (non-accumulative behavior).

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?

Four tightly constructed sentences progress logically from purpose → prerequisite → parameter handling → batching constraints. Every sentence carries essential behavioral or workflow information with zero 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?

For an update tool with optimistic locking complexity, the description completely covers the required workflow (state→update), concurrency requirements, and partial update semantics. No output schema is present, but none is needed for this mutation tool.

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?

While schema coverage is 100%, the description adds crucial usage semantics: it explains that 'version' comes from the state call (concurrency control), that 'sessionId' ties to the open session, and mandates partial update patterns (omit unchanged fields).

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 ('Update') and resource ('fields in the already-open Profit Margin Calculator'), clearly distinguishing it from sibling tools like mg_calculator_profit_margin (open) and mg_calculator_profit_margin_state (read-only).

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 explicit prerequisites ('ALWAYS call mg_calculator_profit_margin_state first'), names the specific sibling tool to use, explains the rationale (avoiding overwriting manual GUI changes), and mandates batching ('Send all changes in a single call').

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 provided, so description carries full burden. It compensates by listing return fields (names, descriptions, categories, resource URIs), which is crucial given no output schema exists. However, lacks disclosure of pagination, error cases, or performance characteristics.

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, zero waste. First sentence establishes purpose and return payload; second provides usage guidance. Information is front-loaded and dense.

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 simplicity (1 optional param, no nested objects) and lack of output schema, the description adequately compensates by enumerating return fields. Would benefit from mentioning the return structure (list/array), but sufficient for tool selection.

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% with the 'category' parameter fully documented ('Filter by category. Omit to list all tools'). Description mentions 'filter by category' which aligns with schema but adds no additional semantic depth beyond the schema definition. Baseline 3 appropriate for high-coverage schemas.

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?

Excellent specific verb (List) + resource (Marketgenius tools) + scope (names, descriptions, categories, resource URIs). Clearly distinguishes from sibling calculator tools by positioning itself as the discovery/meta tool for finding available tools.

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 clear usage context ('Use mg_list to discover what's available') and mentions filtering capability. Could explicitly contrast with specific calculator tools (e.g., 'use this before invoking specific calculators'), but 'discover what's available' effectively conveys the intent.

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