Sourcey

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

The annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior, so the safety profile is covered. The description adds a real semantic guarantee beyond them: unknown eligibility and unsupported stacking stay explicit rather than being inferred, which tells the agent how to read the comparison result. It does not say whether the call fails on unknown slugs or how unknowns are flagged, so it stops short of full disclosure.

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 filler. The core action and its scope lead, and the caveat about unknowns is held back as the closing clause where it belongs.

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?

An output schema exists and annotations carry the safety profile, so the description does not need to explain return values. What it does provide, the compared dimensions and the guarantee that unknown eligibility and unsupported stacking remain explicit, covers the important semantics. It omits error behavior for invalid or unknown offer slugs, which a comparison tool with 2-10 required inputs would benefit from stating.

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%: 'offers' documents the 2-10 range and ordering, and 'facts' documents typed company facts used only for explicit eligibility evaluation. The description's phrase 'including value, access requirements, eligibility, freshness, and evidence' loosely maps to what facts feed, but adds no syntax or format meaning beyond the schema. Baseline 3 for a fully described 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?

Names a specific verb and resource ('Compare two to ten startup credit or deal offers side by side') and enumerates the comparison dimensions: value, access requirements, eligibility, freshness, evidence. That clearly separates it from search_offers or inspect_evidence, though those siblings are never named, so the differentiation is implied rather than stated.

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 two-to-ten bound and 'compare in this order' hint at when this tool applies, but there is no explicit guidance on when to use compare_offers instead of search_offers or inspect_evidence, nor any stated prerequisites (for example, that offer slugs must already be known). Usage is inferable but not spelled out.

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 declare readOnly, idempotent, non-destructive, and closed-world behavior, so the safety profile is covered. Beyond that, the description adds that the feed is 'signed' (integrity/authenticity context) and what categories of change it emits, which is genuine added value. It stops short of describing ordering, page size, or how the feed terminates.

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?

One sentence, front-loaded on the verb and the core resource, with no filler. The enumeration of change types and entity types is dense but each item serves to scope what the feed returns.

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?

An output schema exists, so return values and cursor shape need not be explained here, and annotations carry the safety profile. The description covers scope and entity breadth adequately; only paging/ordering details are absent, which is a minor gap for a change-feed 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?

With a single parameter at 100% schema coverage, the schema already explains that cursor is an opaque signed value from the previous page. The description only adds that the cursor is optional, which is marginal beyond the structured field, so the baseline 3 applies.

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 a specific verb (track) and resource (Sourcey's signed change feed), and enumerates both the change kinds (added, changed, withdrawn, removed) and the entity types covered (credits, discounts, free tiers, perks, deals). This framing is unmistakably distinct from the search/compare siblings, so an agent can select it without opening a schema.

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 phrase 'after an optional cursor' implies this is a paging/polling endpoint, which is useful implied usage guidance. However, it never states when to call this versus search_offers or compare_offers, nor when to omit the cursor (first page), so guidance is only inferred.

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 declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuine domain rules beyond that — the proof field reproducing a failure "never moves the letter," and the F-card case where the interface path is absent — but most of its length restates returned fields that the output schema already defines.

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 purpose is front-loaded correctly, but the body is a single run-on sentence enumerating roughly a dozen return fields, most of which duplicate the output schema. A shorter sentence pointing to the schema plus the resolution rule would carry the same information at half the length.

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?

With an output schema present, the long field inventory is largely wasted effort, while the genuinely ambiguous parts — zero required parameters, how partial argument sets are handled, and error behavior for an unknown profile ID — go unaddressed. Complete enough to call, but not complete enough to call confidently in edge cases.

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 only 25%, so the description must compensate, and it does: it establishes that profile_id is an alternative to the entity+product+job triplet and stresses "exact" product and job, implying slug matching rather than fuzzy lookup. It stops short of explaining the arp_ ID format or what happens when neither resolution path is fully supplied.

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?

Opens with a specific verb+resource ("Get one published Agent Readiness report card") and clarifies single-record scope, which implicitly separates it from the sibling search_readiness. However, it never names search_readiness or inspect_evidence, so the sibling differentiation is left to inference.

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?

"Resolve by immutable profile ID or by one Entity plus exact product and job" gives the two valid lookup shapes, which is real usage guidance for a 0-required-param tool. But there is no statement of when to prefer this over search_readiness or inspect_evidence, and no mention of what an invalid combination yields.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's job is added context — and it delivers: the current report is 'written at most once a day from the release current then' (a real freshness/staleness caveat) and release-pinned reports are immutable and 'kept for citing.' 'Each answer carries the page it is read at' hints at response shape beyond the 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 whole definition is a single sprawling sentence with nested parentheticals ('offers by size, by how a startup reaches them and by their terms; report cards by grade, by step and by category'), which is hard to scan. The report names are front-loaded, but the enumeration of payload contents is padded and could be compressed or pushed to the output schema.

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?

With two parameters, an output schema, and full annotation coverage, the description supplies what's missing: payload composition, current-vs-archival semantics, freshness cadence, and citation behavior. Little an agent needs to call it correctly is absent.

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 both parameters are already documented; the description nonetheless adds semantics the schema lacks — that release_id selects an archival, citation-stable snapshot while omission yields a cached daily-refreshed current report, which matters for reproducibility.

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 first clause names the specific resources retrieved ('the State of Startup Credits or the State of Agent Readiness report') and enumerates the payload (figures, names, fact sheets, prose), so the agent knows exactly what comes back. It stops short of naming which sibling to prefer when, but the resource is unmistakable.

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 only usage guidance is parameter-scoped: omit release_id for the current report, supply it to read a report 'as written from that release, kept for citing.' There is no statement of when to call get_report rather than get_readiness, get_changes, or compare_offers, so the sibling choice is left to inference.

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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that by confirming the tool 'never signs, settles, or interprets a payment' and that payment/job status live elsewhere, which sets clear expectations about side effects and scope.

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 filler, and the primary capability is front-loaded before the scope limitation. Every clause carries information: service list, resource contracts, pricing, policy links, and the payment boundary.

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?

Return values need not be explained because an output schema exists, and the description still previews what the payload contains. With no inputs, strong annotations, and an explicit scope boundary, everything an agent needs to call this correctly is present.

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?

There are zero parameters, so there is nothing for the description to compensate for; the baseline for a no-param tool is 4. The description correctly avoids describing inputs and instead frames the tool as parameterless discovery.

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 names a specific verb and resource: discovering Sourcey's enabled paid agent services and canonical HTTP resources, with concrete payload contents (request/response contracts, price floor, policy links, x402 discovery). It is clear on its own but never differentiates itself from sibling tools like search_offers or compare_offers, which also concern paid offerings.

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?

Usage is implied rather than stated: an agent infers this is the entry point for enumerating available paid services. The one explicit boundary clause ('Payment and durable job status remain on the product HTTP API') is a useful when-not, but it points outside the MCP server rather than routing to a sibling tool, and no when-to-use condition is given.

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 declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine behavioral content by disclosing that resolution surfaces freshness and dispute status, telling the agent this is a provenance audit rather than a plain lookup.

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 tight sentences with no filler; the domain scope is front-loaded and the resolution behavior follows immediately.

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?

With an output schema present and annotations covering the safety profile, the description only needs to orient the agent — which it does by naming the domain and the returned evidence types. Minor gap: no indication of whether digests from any source are acceptable or what happens with unknown/stale digests.

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% and the single parameter is already documented with its source and format. The description restates the cardinality ('one to ten') and the 'exact revisions' expectation, adding emphasis but no format or syntax detail beyond the schema. Baseline 3 applies.

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 a concrete verb ('Inspect') and resource ('the provenance behind startup credits and deals') and specifies what it resolves revisions into ('supporting events and observations'). It is clear on its own, though it does not explicitly distinguish itself from sibling readers like get_changes or compare_offers.

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?

No when-to-use or when-not-to-use guidance is given, and no sibling alternative is named. The closest thing to context is the implicit dependency on revision digests produced by search/comparison, which lives in the schema rather than the description, and even that is not framed as a prerequisite.

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 declare readOnlyHint, idempotentHint, and destructiveHint=false, and the description is consistent with them (it produces a draft, not a write). Beyond the annotations it adds real substance: drafts grant no publication, verification or grade, and startup credits/deals never count as service readiness — non-obvious domain rules an agent would otherwise get wrong.

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?

Only two sentences, and the scope/precondition is reasonably front-loaded, but the first sentence is a ~60-word comma-chained list that is hard to parse and buries 'one service and job' inside enumerations. Every clause is defensible content; the structure, not the length, is the problem.

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?

Return values are covered by the output schema, so that gap is excused. For a tool with 12 required parameters and deep nesting, though, an agent is left without guidance on the relational structure (how relations, resources, and surface_exclusions interlock) or on what a valid command_contract value must be, which is a meaningful omission given the schema's zero description coverage.

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% across 18 parameters, so the description must carry the burden and it only partially does: it explains the intent of participants, endpoints, interfaces, job_operations ('the request the probes send with no account, or the operation in the vendor's OpenAPI document'), and job_bindings. Key required parameters like relations, resources, scope_source_uris, subject_roles, surface_exclusions, and command_contract get no mention at all, leaving most of the contract 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 opens with a specific verb+resource ('Prepare the canonical Agent Readiness declaration') scoped to 'one service and job', and enumerates the constituent pieces (participants, endpoints, interfaces, job operations, job bindings). It doesn't explicitly name siblings like get_readiness or search_readiness, but the authoring verb clearly separates it from the read-side tools in the set.

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?

It states a hard precondition ('The company must already exist in Sourcey and resolves by exact identity') and the failure mode ('an unknown company returns identity_allocation_required'), plus the follow-on step ('Complete declarations use POST /v1/submissions as product agent_readiness'). What's missing is an explicit statement of when an agent should use this versus inspecting existing state with get_readiness/inspect_evidence first.

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 declare readOnly, idempotent, closed-world and non-destructive behavior, so safety needs no restating. The description adds real behavioral context beyond them: facts are used only for explicit eligibility evaluation, and 'unknowns remain explicit' signals that missing facts are not guessed or filled in — a meaningful expectation for the agent's output handling.

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 dense sentences with the search scope front-loaded and no filler. The trailing clause 'unknowns remain explicit' is terse to the point of being slightly cryptic, keeping it just below the top mark.

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?

With a fully described schema, a nested typed-facts object, rich annotations and an output schema, the description needs only to frame intent and filtering — which it does. Nothing critical is missing, though a note on how it differs from compare_offers would complete the picture.

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%, so all five parameters are already documented in the schema, setting the baseline at 3. The description adds conceptual framing for the filters but also says 'vendor' where the schema names the parameter 'entities' (entity slugs/IDs), a small terminology drift that adds no precision.

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 gives a specific verb+resource ('Search current startup credits and deals') and enumerates the covered categories (cloud credits, SaaS discounts, free tiers, grants, perks, partner offers), which tells an agent exactly what corpus is searched. It stops short of naming the closest sibling, compare_offers, so the search-vs-compare boundary must be inferred.

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?

It implies usage context ('Filter by query, vendor, or category and evaluate eligibility from typed company facts'), which is enough to infer that this is the discovery entry point before comparison. There is no explicit when-not or named alternative such as compare_offers or get_readiness to route an agent away from 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 already declare readOnly, idempotent, non-destructive, closed-world, so the safety bar is low; the description still adds real behavioral meaning — what a card contains (letter, six stages, human-step frequency, reachability, reproduced vendor failure, evidence label, freshness, canonical URL) and the non-obvious rule that a fresh-run proof never changes a step or the letter. The only missing behavior is result volume/pagination, which the schema's limit partially covers.

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?

Purpose is correctly front-loaded, but the remainder is a single semicolon-chained sentence enumerating stages, labels, and output fields, which is hard to parse and partly duplicates the schema's label and letter enums. Every element is on-topic, yet the structure obscures it.

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 read-only search with full schema coverage, an output schema, and complete annotations, the description covers the domain model an agent needs to interpret results. What remains unstated — the relationship to get_readiness and result ordering — is minor but not trivial for a 7-parameter search 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 description coverage is 100%, so the schema already defines job, label, limit, query, entity, letter, and product in detail. The description reinforces the probed vs vendor_run_verified distinction but adds no syntax or format guidance beyond the schema for the other five parameters, so baseline 3 applies.

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?

Opens with a specific verb+resource: 'Search published Agent Readiness report cards.' The description makes clear these are graded per-job per-vendor artifacts, but it never distinguishes this search from the sibling get_readiness, so an agent must infer that one finds and the other fetches.

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?

Usage is implied rather than stated — filters like job, product, entity, letter, and label suggest a filtered lookup, and the closing note 'Service readiness is separate from startup-credit eligibility' usefully steers away from credit/offer queries. But there is no explicit when-to-use, when-not, or named alternative (e.g., get_readiness) anywhere in the text.

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