marketsharp-mcp

marketsharp_opportunities_list

Read-onlyIdempotent

List jobs and leads changed since a given date with contract status, totals, sale and contract dates, and balance due; adjust the record limit to avoid incomplete results.

Instructions

List opportunities (jobs and leads) changed since a date, with job numbers, sale and contract dates, contract totals, contract status and balance due. Returns at most numberOfRecords (max 1000) with no paging. If you get exactly that many, the list may be incomplete: raise numberOfRecords (up to 1000), and say the result may be incomplete if it is already 1000. Needs MarketSharp's View Opportunity permission.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fromDate": "<fromDate>"
    },
    "name": "marketsharp_opportunities_list"
  }
}

Input Schema

Name	Required	Description	Default
`fromDate`	Yes	Only jobs and leads changed on or after this date. Date/time in the MarketSharp company time zone, e.g. 2026-10-01 or 2026-10-01T08:00:00.
`numberOfRecords`	No	Most records to return (default 100).

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.0.0Nov 11, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the description is free to add genuinely new behavior: there is NO paging, the result is capped at numberOfRecords (max 1000), a full-cap result may be silently incomplete, and the caller must surface that caveat to the user. It also names the required MarketSharp 'View Opportunity' permission, which is an auth prerequisite annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with what is returned, then the cap/paging constraint, then the permission requirement 'closing' the description — a sensible information order with no filler. The truncation sentence is slightly tangled ('raise numberOfRecords (up to 1000), and say the result may be incomplete if it is already 1000'), costing a point on clarity rather than length.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by naming the returned fields; params, permission, paging behavior, and the incompleteness failure mode are all covered. It never states result ordering or the shape/format of the returned objects (types, nesting), which is the one remaining gap for an agent assembling a response.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented with format examples and min/max bounds. The description reinforces the max-1000 ceiling and the raise-and-retry strategy but adds no new syntax, default, or edge-case meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List opportunities (jobs and leads) changed since a date') and enumerates exactly which fields come back (job numbers, sale/contract dates, contract totals, status, balance due). It does not distinguish itself from siblings like jobs_search or inquiries_list, so an agent must infer that 'opportunities' is the combined job+lead view rather than one of the dedicated search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'changed since a date' clearly frames this as an incremental/delta sync tool and the truncation paragraph gives an explicit corrective action (raise numberOfRecords, tell the user if already at 1000). It stops short of naming when to prefer this over jobs_search or inquiries_list for a single-record lookup, so guidance is strong but not complete.

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