Direct answer
The Investment Glossary Sense Resolver disambiguates finance terms that have multiple meanings (such as margin, yield, spread, basis, duration or equity) and routes the reader to the correct Swoopr definition and deeper guide. The tool is educational. It organizes information, exposes relationships, or performs deterministic logic from the inputs shown on the page. It does not recommend an investment, predict an outcome, or substitute for individualized financial, tax, legal, or regulatory advice.
The problem this tool solves
A one-word finance search can return a technically correct but contextually wrong definition. 'Margin' can mean borrowing in a brokerage account or a business profitability ratio. 'Spread' can mean bid-ask, credit, option or rate spread. The resolver makes the ambiguity visible instead of silently choosing.
What you enter or select
Required input: a term or alias.
Optional context:
- stocks/company analysis;
- trading/market structure;
- bonds/fixed income;
- ETFs/funds;
- options/derivatives;
- retirement/accounts;
- taxes;
- portfolio/risk;
- crypto;
- real estate;
- macroeconomic data.
The tool should also accept common abbreviations and punctuation variants through the glossary alias index.
The interface should explain each input next to the control. If an input is optional, say what happens when it is omitted. If the tool uses a registry or external data source, show the source and freshness metadata separately from user-entered information.
What the tool returns
Return:
- canonical term matches;
- plain-English one-sentence definitions;
- domain/context labels;
- “commonly confused with” relationships;
- formula link where relevant;
- canonical guide;
- relevant public tool;
- source/review date for time-sensitive rules.
When a query is unambiguous, return the one canonical sense. When several senses remain plausible, ask the user to choose context rather than guessing.
Results should be grouped into observed/selected facts, Swoopr-calculated or matched output, and next educational steps. A result label must never look like a personalized recommendation. If the tool cannot resolve the inputs confidently, it should return an explicit “needs review” or “insufficient information” state.
Methodology
Use the canonical glossary registry and alias map.
Normalization can include case folding, punctuation normalization and approved abbreviation lookup. Fuzzy matching can suggest terms but must not automatically merge them.
Resolution order:
- exact canonical term;
- exact alias;
- context-filtered exact alias;
- reviewed fuzzy candidates;
- no confident match.
Each candidate retains one concept ID even when multiple aliases point to it.
The methodology must be visible from the tool page and available without opening a modal that requires JavaScript. Deterministic rules should be documented in plain English and, where helpful, as readable pseudocode. Data-driven outputs should include the registry revision or data timestamp used.
Worked examples
Margin: return Brokerage Margin, Gross Margin, Operating Margin and Net Margin as separate concepts, with context prompts.
Yield: return Yield to Maturity, Current Yield, Dividend Yield, SEC Yield, Distribution Yield and other canonical senses in the registry.
P/E ratio: aliases such as PE Ratio and Price/Earnings Ratio resolve to the same canonical concept, not several choices.
Equity: surface the relevant investment-security, accounting or ownership senses if Swoopr models them separately.
Examples should use hypothetical or clearly educational inputs unless the tool is explicitly designed to read public, current source data. Examples are demonstrations of method, not suggested actions.
Accessibility requirements
The tool must be usable with keyboard, screen reader, zoom, high contrast and reduced motion.
Every form control needs:
- a persistent programmatic label;
- units where relevant;
- inline help that does not depend on hover;
- errors associated with the field;
- a clear reset path.
Results must be announced appropriately without forcing focus unexpectedly. If the tool uses cards, a graph, chips or color-coded categories, the same information must be available in text. Do not use color as the only indicator of category, severity or status.
The tool should remain understandable if charts fail to load. Tables should use real table semantics. Controls that behave like buttons must be real buttons.
Privacy and data handling
Prefer browser-local computation for this tool when practical. Do not request account credentials, passwords, private keys, seed phrases, brokerage tokens or other secrets.
If a backend lookup is required, transmit only the information necessary for that lookup. Do not persist user inputs unless the product explicitly provides a save function and explains the storage behavior.
Limitations
Natural language can use terms loosely, and the same phrase can be ambiguous even with a selected domain. Fuzzy matching is a discovery aid, not an identity decision. New aliases and concept merges require editorial review.
A useful limitation statement explains what the tool does not know. Avoid generic disclaimers that hide the actual uncertainty.
Interlinking plan
Link to the Investment & Trading Glossary, Knowledge Center, canonical guides for the returned concepts, formula pages, relevant tools and disambiguation pairs.
Each internal link should represent a typed relationship: EXPLAINS, IMPLEMENTS, REQUIRES_KNOWLEDGE_OF, SUPPORTED_BY, COMPARES_WITH, NEXT_TOPIC, or another documented predicate. Do not create a block of loosely related links for SEO.
Structured data and graph identity
Create one stable PublicTool entity ID and one page resource.
The page should be ABOUT the tool. The tool should connect to every concept it implements or explains. If a methodology page exists, use EXPLAINED_BY or the equivalent Swoopr predicate.
Do not expose backend function names as separate public tools.
QA and validation
Before release, test:
- empty and incomplete input;
- boundary cases;
- invalid combinations;
- keyboard-only operation;
- screen-reader labels and live-region behavior;
- browser zoom at 200% and 400%;
- no-JavaScript fallback content;
- deterministic repeatability;
- registry/data-source freshness;
- internal-link resolution.
Automated tests should compare known fixtures with expected output. Any rules stored in code and copy must be generated from one source or validated against each other so the methodology cannot drift from the implementation.
Design deep dive 1: Alias governance
Aliases improve search but can also create accidental merges. Every alias assignment should be reviewable and should point to one canonical concept ID unless the alias is intentionally ambiguous.
Implementation exercise: Build fixtures for P/E/PE and for ambiguous words such as margin or spread.
Release check: Exact alias resolution may be automatic only when the alias registry says the mapping is unambiguous.
This design note belongs in the public methodology because it explains how the tool avoids a specific failure mode. The interface copy can be shorter, but the underlying behavior should remain testable. Where the behavior depends on registry data, include the registry revision in the diagnostic output so a stale configuration can be distinguished from a logic defect.
Design deep dive 2: Context narrowing
Context should narrow candidates without deleting valid meanings from the registry. Selecting fixed income can prioritize credit spread and yield spread while leaving the user able to view other senses.
Implementation exercise: Test the same word under stocks, fixed income, options and general context.
Release check: Context changes ranking/display, not canonical identity.
This design note belongs in the public methodology because it explains how the tool avoids a specific failure mode. The interface copy can be shorter, but the underlying behavior should remain testable. Where the behavior depends on registry data, include the registry revision in the diagnostic output so a stale configuration can be distinguished from a logic defect.
Design deep dive 3: Confusion pairs
The resolver should surface explicit DIFFERS_FROM relationships such as return versus yield or volatility versus risk when a query commonly causes mistakes.
Implementation exercise: Create a reviewed list of confusion pairs rather than deriving them from word similarity.
Release check: The tool should explain the difference in one or two sentences and link to both canonical concepts.
This design note belongs in the public methodology because it explains how the tool avoids a specific failure mode. The interface copy can be shorter, but the underlying behavior should remain testable. Where the behavior depends on registry data, include the registry revision in the diagnostic output so a stale configuration can be distinguished from a logic defect.
Design deep dive 4: Fuzzy matching safety
Typo tolerance is useful for discovery but dangerous for identity. Fuzzy results should always be labeled suggestions until the user selects one.
Implementation exercise: Test close strings that correspond to different concepts.
Release check: No fuzzy match may write back to the alias registry automatically.
This design note belongs in the public methodology because it explains how the tool avoids a specific failure mode. The interface copy can be shorter, but the underlying behavior should remain testable. Where the behavior depends on registry data, include the registry revision in the diagnostic output so a stale configuration can be distinguished from a logic defect.
Design deep dive 5: Deep-link behavior
Every resolved sense should expose a stable term URL or fragment, canonical guide and relevant tool/formula if available.
Implementation exercise: Test direct links with JavaScript disabled and with search state restored from the URL.
Release check: The resolver should improve glossary navigation without creating indexable search-parameter duplicates.
This design note belongs in the public methodology because it explains how the tool avoids a specific failure mode. The interface copy can be shorter, but the underlying behavior should remain testable. Where the behavior depends on registry data, include the registry revision in the diagnostic output so a stale configuration can be distinguished from a logic defect.
Additional test scenario: Fuzzy matching safety
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Context narrowing
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Alias governance
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Fuzzy matching safety
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Context narrowing
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Alias governance
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Fuzzy matching safety
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Context narrowing
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Alias governance
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Fuzzy matching safety
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Context narrowing
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.
Additional test scenario: Alias governance
Create a fixture that deliberately violates one assumption of the tool, run it through the core logic, and record the expected safe failure state. The user-facing result should explain what could not be resolved without inventing missing information. The diagnostic output should identify the input category, registry revision and rule that caused the stop.
Then repeat the fixture with the missing information supplied from a reviewed registry entry. The result should become deterministic without changing any unrelated output. This paired test demonstrates that the tool is driven by explicit evidence rather than hidden scoring or broad text generation.
Document the scenario in the component test suite and link the relevant methodology section from the test name. That keeps implementation, public explanation and QA synchronized.