CULT+MATH Decision Briefs

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

Annotations already declare readOnly=false and openWorld=true, so the write/external nature is covered; the description adds real value by naming the payment provider (Stripe), the human approval gate, and the session_id handoff. It does not say what happens on repeated calls (annotations say non-idempotent, but the description never clarifies that each call creates a new checkout session) or how failures/expired sessions behave.

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 tight sentences: purpose first, then return values and the follow-up call, then the safety instruction. Every sentence carries actionable information and nothing is repeated from the schema or title.

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?

Although there is no output schema, the description covers return values (checkout URL, session_id), the required input provenance, the next tool call, and the human-approval constraint. For a one-parameter tool this leaves no significant gap an agent would need to call it correctly.

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

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

There is a single parameter at 100% schema description coverage, which itself points to list_decisions as the source with an example format. The description adds nothing about decision_id beyond that, so the schema baseline of 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 and resource: 'Starts a Stripe checkout for the full evidence behind one decision', and enumerates what the purchase includes (sourced/dated figures, what would flip the answer, stated limits). It is clearly distinguished from the sibling get_decision_evidence, which is framed as the post-payment step.

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?

Gives explicit sequencing: call this to pay, then 'After the user pays, call get_decision_evidence with both ids.' It also states a hard prerequisite — 'Always show the price and get the user's go-ahead before sending them to pay' — so the agent knows both when to call it and what must precede it.

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 genuinely new behavioral context beyond that: the response is the complete public metadata set, while the PDF itself is gated behind payment – an important expectation about what the call will and will not yield.

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, both earning their place: the first front-loads the payload contents, the second delivers the paywall caveat. No filler or restatement of the title.

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 no output schema, the description carries the return-value burden and discharges it by enumerating the returned fields, including the payment link. For a one-parameter read tool with full annotation coverage, nothing needed to call it correctly is missing.

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% and the single id parameter is already documented with an example value sourced from list_decision_briefs, so the schema does the work. The description adds no format or origin detail about the id beyond what is structured.

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?

"Everything public about one brief" plus an enumeration of the returned fields (six decisions with evidence lines, pages, price, sample pages, license, payment link) is a specific resource-plus-content statement. It does not name a sibling, but the second sentence implicitly separates it from the purchase path (buy_decision_evidence) by noting the PDF requires payment.

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: use it when you have a brief id and want its public details rather than the paid artifact. There is no explicit when-to-use/when-not, and no pointer to the alternative for obtaining the actual PDF, so the agent must infer the routing.

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 open-world behavior, so the description only needs to add context. It does: the access is entitlement-gated on payment, and the accepted session_id may come from a single decision purchase or from a bundle (full brief, team license, pack, all-access). The only gap is the failure mode for unpaid or expired sessions.

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 paid-access constraint is front-loaded before the parameter guidance. Every clause carries information the agent needs to select and call the tool.

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, two-parameter tool with no output schema, the description covers the access model and both input sources adequately. A brief note on what 'evidence' contains or what an unpaid call returns would close the remaining gap.

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 50%, and the description meaningfully extends the session_id parameter beyond the schema's 'Stripe Checkout Session id' by explaining its two provenance paths. decision_id remains undocumented in both places, though 'one decision' / 'this decision' makes its role inferable.

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 and resource ('Returns the full evidence for one decision') plus the gating condition ('once it is paid for'), which distinguishes it from the brief-oriented sibling. It stops short of explicitly contrasting itself with get_decision_brief, so the distinction between 'evidence' and 'brief' is left implicit.

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 the key precondition (the decision must be paid for) and tells the agent where to obtain the session_id, naming buy_decision_evidence and the qualifying purchase types. It does not say what to do when the prerequisite is unmet (error vs. empty result) or point to a fallback tool such as get_decision_brief.

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 is free to spend itself on payload behavior – and it does, enumerating the finding content plus date, license, citation line and related brief, which matters because there is no output schema. It omits failure behavior for a bad or unpublished URL, which keeps it short of a 5.

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 compact sentence with zero padding, and the resource scope leads before the return fields. It reads as a noun phrase rather than a directive, which slightly weakens front-loading but wastes no words.

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

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

With no output schema, the description usefully compensates by enumerating returned fields, and one parameter at full schema coverage leaves little else to explain. Not addressed are edge cases like invalid or unpublished URLs, or whether the answer page and study page return different shapes.

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% and the single url parameter is fully documented in the schema, including the accepted path forms and provenance from search_cultmath. The description adds no syntax, normalization or fallback detail beyond that, 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?

The description names a specific resource (all published findings of one CULT+MATH study or answer page) and lists what is returned (date, license, citation line, related brief), which clearly separates it from a search tool. It never states an explicit verb such as 'retrieve' or 'fetch', so the action is inferred rather than declared.

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 only implied: the schema notes the URL comes from search_cultmath, so an agent can infer this is the follow-up fetch step after a search. Nothing says when to prefer this over get_decision_brief or get_decision_evidence, and there are no exclusions or prerequisites stated.

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. The description adds genuine value beyond them by disclosing what the response contains — per-brief audience, headline finding, price, page and payment link — and that bundles and the custom brief are included in the listing. It stops short of describing pagination or ordering.

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 front-loaded sentence plus a short trailing clause about bundles and the custom brief; every element carries information and nothing is padded. Slightly dense colon-list phrasing, but no wasted text.

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 no output schema, the description takes on the job of explaining return contents, and it does so at the field level, which is the key information an agent needs to decide to call this for discovery or pricing. The missing piece is any hint about the optional category filter or result ordering, but the schema covers the former.

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 optional 'category' parameter is documented in the schema with examples, so the description has little to add. It does not mention the category filter at all, meaning it neither reinforces nor extends the schema — baseline 3 is appropriate.

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

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

The description names a specific verb ('List') and resource ('CULT+MATH Decision Briefs') and even enumerates the attributes of each brief (audience, headline finding, price, page, payment link) plus bundles and the custom brief. It does not, however, distinguish this listing tool from siblings like get_decision_brief or list_decisions, so an agent must infer the boundary.

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 only implied: 'List' suggests a browse/discovery use case versus a single-item fetch, but there is no explicit statement of when to call this instead of get_decision_brief or list_decisions, and no exclusions or prerequisites are given. Adequate but leaves the routing decision 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 readOnly, idempotent, non-destructive, closed-world behavior, so safety is covered. The description adds genuinely useful behavior beyond that: the result set is capped at 54 items in fixed groups of six, and each item exposes only a summary evidence line rather than the paid full evidence — critical context for an agent deciding whether to list or buy. Pagination and exact return shape remain unexplained.

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, no filler: the first defines the payload and its fields, the second hands off to the purchase tool. The handoff instruction is placed after the payload description, which is the right order for an agent scanning for what it gets first.

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 only two optional parameters and no output schema, the description must explain the return payload, which it does at the field level. The gap is narrow: it does not say whether all 54 decisions are returned in one call or how the six-per-brief grouping is represented structurally.

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 both optional parameters are already documented as keyword and brief filters. The description adds no extra syntax, matching rules, or interaction between query and brief_id, so it does not exceed the baseline that a fully documented schema sets.

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 resource (the 54 decisions, six per brief) and enumerates what each row carries: owner, contester, and the public evidence line. This is clearly distinct from list_decision_briefs (briefs) and get_decision_evidence (full evidence), so an agent can tell the siblings apart 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?

It gives concrete downstream routing: take an id from here and pass it to buy_decision_evidence to purchase that decision's full evidence. It does not say when to prefer get_decision_brief or list_decision_briefs first, so the guidance is one-directional rather than complete.

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?

Very rich beyond annotations: it states it returns no answers, that platforms citing no sources count as not measured, that fewer than 3 measured platforms makes the run unsound, and that this call charges nothing while payment happens via MPP/HTTP 402 with a Stripe token. The charge-only-if-controls-pass rule and the read-only, no-charge framing are consistent with readOnlyHint and destructiveHint=false.

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 question hook is front-loaded and each sentence carries operational weight: what is measured, what is not returned, soundness rule, payment flow, billing condition. It is dense but slightly long, and some phrasing is promotional rather than purely informational.

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 no output schema, the description still explains the return payload (measurement plus payment_url, price, instructions) and the downstream payment step. It also flags the failure mode (unsound run under 3 measured platforms) and the billing guarantee, so an agent knows exactly what happens after invoking.

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 both parameters are already documented, including the subdomain rule. The description reinforces that the question must be a real buyer question asked live with web search on, but adds no format, length, or validation semantics 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?

The description opens with a concrete question that defines the measurement: whether a domain is cited by ChatGPT, Claude, Gemini and Perplexity for a buyer question. It then enumerates exactly what the result contains (per-platform citation, position, platform count, top competing domains), which distinguishes it from siblings like run_peer_benchmark or search_cultmath.

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 context is clear: ask a buyer-style question about a domain's AI citation footprint, and expect a quote-stage tool that must be followed by a POST to payment_url. It does not explicitly name alternatives or say when a sibling tool is a better fit, so it stops short of the 5 bar.

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?

Goes well beyond the annotations by disclosing the billing model (no charge here, charge only if the run passes controls), the two built-in controls (competition as filer denominator, shrinkflation must be 0), the presence of stated limits and a run id, and the dated citation line. This is consistent with readOnlyHint=true since the tool performs no mutation and incurs no cost.

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-loads the deliverable and the no-charge behavior, then the payment mechanics, with no filler sentences. Density is high and jargon like MPP and 'shrinkflation' is used without definition, which costs a bit of readability.

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 no output schema, the description carries the return-shape burden and does so: payment_url, price, instructions, run id, and citation line. For a three-parameter quoting tool, everything an agent needs to call it and act on the result 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?

Schema description coverage is 100%, with start, end, and phrase already fully documented including defaults, bounds, and an example. The description adds no syntax or format detail beyond the schema, so the baseline of 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 and resource: measures what share of U.S. 10-K filers mention a phrase year by year from SEC EDGAR full-text search, and clarifies this specific tool only validates the request rather than running anything. The 10-K/phrase framing clearly separates it from sibling trend tools such as run_regulatory_trend, run_spend_trend, and run_ai_visibility.

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?

Gives explicit operational guidance for the follow-up step: the tool charges nothing, returns a payment_url, and payment is made by POSTing over MPP with an HTTP 402 and a Stripe shared payment token. What's missing is explicit routing guidance against siblings (e.g., when to pick this over run_regulatory_trend or run_triangulation), which the agent must infer from the 10-K domain.

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

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

Beyond the annotations, the description discloses the cost model (this call charges nothing, returns payment_url/price/instructions), the exact payment protocol (MPP, HTTP 402, Stripe shared token), and the charge condition (only if the run passes its controls). It also describes output behavior — named exclusions with reasons and per-figure 10-K citations — which is exactly the behavioral context annotations cannot convey.

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 output scope is front-loaded, followed by controls, then the payment mechanics, so the agent learns what it gets before how it pays. Sentences are long and dense with parentheticals, but essentially every clause carries information an agent needs to act correctly.

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 paid, asynchronous-style tool with no output schema, the description still covers data source, freshness, peer-count bounds, exclusion reporting, citation guarantees, and return contents (payment_url, price, instructions). Nothing an agent needs in order to call it, or to explain the result to a user, is missing.

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 67%, and the description compensates by expanding the metric enum into plain-language definitions (revenue growth, gross margin, R&D and sales-and-marketing as a share of revenue) and restating the 2-6 peer constraint and fiscal-year alignment. The ticker parameter gains no meaning beyond the enum list, which is the only real 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 names a specific artifact (a citable peer comparison of one company's filed metric against 2-6 peers, latest fiscal year, from SEC EDGAR XBRL) and clarifies that the call itself is a quote, not the run. It is clearly distinct from read-path siblings like get_decision_evidence, but it does not explicitly contrast with other run_* siblings such as run_filing_trend or run_triangulation.

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: you call it when you want a peer benchmark, and the description explains the follow-on payment step. There is no explicit 'use this instead of X when Y' routing against the many sibling run_* tools, and no preconditions (e.g., which tickers are valid) beyond what the enum encodes.

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 cover safety (readOnlyHint, idempotent, non-destructive) but say nothing about billing, and the description carries that load: no charge at quote time, HTTP 402 + Stripe shared payment token to pay, and 'charged only if the run passes its controls.' It also discloses the validation contract (a null control phrase must return 0) and what accompanies the result (stated limits, run id, dated citation line) — material behavior an agent cannot infer from structured fields.

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 what is measured, then the contract, then the payment mechanics, then the sibling relationship — a sensible order. It is dense and runs long, but each sentence carries distinct information (denominator, null control, no-charge quote, payment protocol, charge condition, pairing). Minor trimming is possible but nothing is filler.

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?

There is no output schema, and the description compensates by naming exactly what comes back (payment_url, price, instructions; and post-run: limits, run id, dated citation line). Combined with the disclosed charge condition and control requirement, an agent has everything needed to call this correctly and to explain the result to a user.

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%, including the agency enum and start/end defaults, so the baseline would be 3. The description adds genuine meaning beyond that by defining what 'phrase' is counted against (the year-by-year denominator of final and proposed rules) and by framing the agency parameter as a scoping choice. It does not walk through start/end semantics (10-year cap, 1994 floor) itself, leaving those to 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?

Opens with a concrete verb+resource+scope: 'what share of U.S. federal final and proposed rules mention a phrase, year by year, from the Federal Register, optionally for one agency.' The denominator is stated explicitly (every final and proposed rule that year), which pins down the measurement. It also names the sibling it pairs with (run_filing_trend), so an agent can place it against the alternative without opening either 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?

Gives clear operational context: the call only validates and returns a payment_url, charges nothing, and the actual run is triggered by POSTing to payment_url over MPP. The sibling note ('pairs with run_filing_trend') frames when this measurement is the right one. It stops short of an explicit when-not or an enumeration of the other run_* siblings, so it is clear context rather than full routing guidance.

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

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

Beyond the annotations it discloses that the call itself charges nothing, returns only a payment_url, price and instructions, and that billing occurs out-of-band over MPP with HTTP 402 using a Stripe shared payment token, with charge contingent on the run passing a null control. It also states what accompanies a successful run (limits, run id, dated citation line), which is exactly the behavioral context an agent needs before committing to a paid workflow.

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 measurement definition and the no-charge disclaimer are front-loaded before the payment mechanics, and every sentence carries information. It is dense and slightly run-on (semicolon chains), but nothing is redundant.

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 no output schema, the description must describe returns, and it does: payment_url, price, instructions on the quote call, and limits/run id/dated citation line on the run. For a paid, two-step workflow this is complete enough for an agent to act correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic meaning: the denominator is all prime contract obligations that year, and a phrase must be selective enough that a null control returns $0. That tells the agent what a valid 'phrase' looks like in a way the schema's 'without quote marks' does not.

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 states a precise measurement: the share of U.S. federal prime contract obligations matching a keyword, by federal fiscal year, sourced from USAspending.gov. That domain specificity (federal prime awards vs. filings/regulatory/peer benchmarks in the sibling set) effectively distinguishes it, though no sibling is named explicitly.

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 gives strong procedural guidance for the paid flow (validate, receive payment_url, POST over MPP, charged only if controls pass), but never says when to choose this over run_filing_trend, run_regulatory_trend or run_triangulation, and offers no explicit exclusions or prerequisites beyond the year limits.

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

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

Beyond the annotations, the description discloses the key behavioral traits: the call only validates the request and charges nothing, it returns payment_url plus price and instructions, payment happens out-of-band via MPP/HTTP 402 with a Stripe shared payment token, and billing only occurs if the run passes its controls. That reconciles the readOnlyHint=true annotation with a paid product and warns that a failed control makes the run unsound.

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 what gets measured, then the payment mechanics, then the billing condition. It is dense but every sentence carries information; the opening sentence is long but reads as one coherent spec rather than padding.

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 no output schema, the description carries the return-value burden and does explain both the immediate response (payment_url, price, instructions) and what a completed run yields (per-source shares by year, direction, agreement). Minor gap: it does not say what the failed-controls response looks like or how results are retrieved after payment.

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 phrase, start, and end are already documented with bounds and defaults. The description adds only the framing that results are per-year, which the schema's year parameters already imply; it adds no new syntax or constraint detail 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?

The description states a specific verb+resource: measure one phrase across three named public sources (SEC EDGAR 10-K filers, Federal Register rules, USAspending obligations) year by year, with per-source controls, direction, and agreement. That scope distinguishes it cleanly from the single-source siblings run_filing_trend, run_regulatory_trend, and run_spend_trend.

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 clear from the triangulation framing (pick this when you want all three sources compared at once rather than one trend tool), and the payment flow is spelled out. What is missing is an explicit exclusion sentence naming when a single-source sibling would be preferable, so the routing is implied rather than stated.

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, openWorldHint=false and destructiveHint=false, so the safety profile is covered. Beyond that, the description usefully discloses the shape of the response (titles, URLs, dates, lead finding, and a pointer to a deeper brief), which annotations and the schema do not provide — especially valuable since there is no output schema.

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 search scope is front-loaded and the return summary follows. Nothing is repeated from the schema or annotations.

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 three-parameter, non-destructive read tool with a fully documented schema, the description covers scope and return contents, which is what an agent needs to call it. It falls short of complete only in not situating the tool against the other research/brief tools in the sibling set.

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 documents query, kind (with an enum) and limit with its 1–10 bound. The description adds only the loose notion of "keywords" and implies a brief may be returned, but does not explain the kind filter options or what limit controls. Baseline 3 is appropriate.

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

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

The description gives a specific verb and resource ("Search the free CULT+MATH studies and answers (and the briefs) by keywords") and lists what comes back (titles, URLs, dates, lead finding, brief). It is clearly distinct from get_document or list_decision_briefs by virtue of being a keyword search, though it does not name those siblings explicitly.

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 intent to keyword-search the corpus is implied, but there is no explicit statement of when to reach for this tool rather than get_decision_brief, get_document, or list_decision_briefs. No exclusions or prerequisites are given, so the agent must infer routing from the sibling names.

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