market-pulse

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, yet the description adds genuinely non-inferable behaviour: it costs one pull when a key is sent and zero when anonymous, it is the only tool whose answer depends on the caller's identity, and it never echoes the key. The missing piece is whether the quota counter is per-connection or per-key, which an agent tracking usage would want.

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 purpose, then usage, then behaviour, then return shape — a sensible ordering with no filler sentences. It is slightly long, and enumerating the return fields is partly redundant given an output schema exists.

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 zero-parameter, read-only diagnostic tool, the description covers triggers, cost model, identity-dependence, and the fact that listings are absent. Return values are also structured in the output schema, so nothing an agent needs 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?

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline applies. The description's only parameter-adjacent content is the note that sending a key changes cost, which is useful framing rather than schema duplication.

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 (report) plus the exact resource set: tier, whether the key was recognised, daily quota and remainder, freshness, and upgrade location. It explicitly separates itself from pulse_jobs ('it returns no listings'), so an agent can route 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?

Gives three concrete trigger conditions (after pulse_jobs shows redacted listings, after a quota refusal, to validate a freshly configured key) and names the alternative tool for listings. This is explicit when-to-use plus when-not-to-use.

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 read-only/idempotent safety, but the description goes well beyond them: it explains the hash-chain provenance (payloadSha256, previousChainHash, chainHash), that unknown id/lane is refused with an error naming it, that the tool works without an API key on the free tier, and that the unfiltered call is large. The only redundancy is restating read-only/idempotent, which does not undercut the added context.

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?

A single dense paragraph that is well front-loaded: retrieval modes first, then usage, then constraints and return shape. Most sentences earn their place, but the 'Returns {count, records[]}...' sentence partially duplicates the available output schema, and 'Read-only and idempotent' repeats the 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 2-parameter read tool with an output schema, the description covers everything an agent needs: the three call shapes, precedence and mutual exclusion, the precondition for lane slugs, error behavior for unknown keys, auth requirements, and the size caveat. Return-value detail is largely carried by the output schema.

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

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

Schema coverage is 100% and the schema already documents id precedence and lane origin, so the baseline is 3. The description adds the mutual-exclusion rule ('pass id or lane, not both') and the consequence of passing neither (the entire, large ledger), which the schema does not state, nudging it above baseline.

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 and resource ('Read the hash-chained evidence ledger') and immediately names the three retrieval modes (by id, by lane, whole chain). It explicitly routes to the sibling pulse_lanes for lane slugs, so an agent can distinguish it from the other pulse_* tools 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?

States concrete when-to-use cases (verify a claim before relying on it, cite sources, audit for tampering), names the alternative for lane discovery (pulse_lanes), states the mutual-exclusion rule ('pass id or lane, not both'), and steers away from the no-argument case because the full ledger is large. Nothing 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?

Goes well beyond the readOnlyHint/destructiveHint=false annotations by disclosing tiered freshness by API key, that a keyed call consumes one pull from a daily quota, that pro+ can trigger a live refresh, and that newer listings are counted as redacted rather than shown. It also states the failure mode (refusal if the persistent store is unavailable), which 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?

Front-loads purpose and output fields before the operational caveats, and every clause carries information an agent would otherwise have to discover. It is a dense, somewhat run-on block that could be split into shorter sentences, but there is no 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?

Covers listing contents, selection guidance, freshness/quota behavior, and failure mode; the explicit return shape is redundant given the output schema but harmless. For a read-only listing tool with several siblings, nothing material 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 description coverage is 100%, so q, lane, limit and status are already fully documented with defaults and constraints. The description adds contextual color (redaction interacts with result counts, lane trust matters) but no syntax or semantic detail the schema lacks. 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 and resource ("List open job listings collected from the agent-accessible lanes") and enumerates the fields returned, so the agent knows exactly what it gets without opening the schema. It also distinguishes itself from sibling pulse_lanes by positioning that tool as prerequisite for trust context.

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

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

Gives explicit when-to-use ("find work an agent can take now") and names the alternative with its qualifying condition ("use pulse_lanes first if you need to know which lanes are trustworthy"). The lane-scoping guidance in the schema is reinforced by the trust framing in the description.

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 safety is covered. The description adds genuinely new context: it works without an API key on the free tier, and an unknown slug is refused with an error naming it. The return-field enumeration overlaps the output schema, but the auth and error behavior are real additions.

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 and routing are front-loaded and efficient, but the sentence listing return fields (description, website, workUrl, apiUrl, accessMethod, payoutMethod, verdict, evidence[]) duplicates what the output schema already provides. Dropping that clause would make the block tighter without losing information.

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

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

For a single-parameter read tool it covers everything an agent needs: purpose, routing to alternatives, auth requirements, error behavior, and an output schema for the return shape. No material gap remains.

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 schema itself documents the slug format ('lowercase, hyphenated', referencing pulse_lanes). The description adds no syntax beyond that, only the error consequence of a bad value. Baseline 3 is correct when the schema does the heavy lifting.

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 ('Get the complete record for one agent-work lane') and immediately enumerates the record's contents. It explicitly distinguishes itself from pulse_lanes (browsing) and pulse_should_i_bid (spend decisions), so an agent can route correctly 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?

Gives an explicit trigger ('Use after pulse_lanes when you need the reasoning behind a grade or the links to act on') plus two named exclusions with the sibling to call instead for each. Nothing about when-to-use 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, non-destructive and closed-world, so the safety profile is covered. The description still adds real behavioral value beyond that: free-tier/no-API-key operation, deterministic answers for identical arguments, the {count, methodologyVersion, lanes[]} return shape, and the specific refusal behavior for out-of-enum filter values. It stops short of describing pagination or result-size limits, which keeps it off 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?

Dense but front-loaded: purpose and the 'use this first' instruction lead, then routing to alternatives, then behavioral guarantees, then return shape. No sentence is redundant or padded.

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 five optional filter parameters, an output schema, and read-only annotations, the description covers everything an agent needs: when to use it, how filters compose, what comes back, and the failure mode for bad enum input. Nothing material 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 description coverage is 100% and each parameter (including enum semantics for grade, freshness, automation) is fully documented in the schema itself. The description only adds the aggregate rule that filters narrow the list and omitting all of them returns every lane, which the schema already implies with 'Omit for every grade' style notes. Baseline 3 applies when the schema does the heavy lifting.

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 ('List the agent-work lanes in the Market Pulse index') and enumerates the lane kinds, so the agent knows exactly what domain this covers. It also names three siblings (pulse_lane_detail, pulse_should_i_bid, pulse_jobs) and what each is for, making differentiation immediate.

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?

'Use this first to discover lane slugs and to shortlist where an autonomous agent can realistically earn' gives explicit when-to-use guidance with a stated goal. It also routes to alternatives by name with the condition that selects each, leaving nothing 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, but the description adds context the annotations cannot: no arguments required, and it works without an API key on the free tier, which matters for an agent deciding whether the call is viable. It also sketches the response shape, though that partially duplicates the 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?

Front-loaded with purpose and content, then routing, then operational notes. Efficient overall, though the enumerated return-shape clause duplicates the existing output schema and 'read-only and idempotent' restates 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?

An output schema exists, so return values need not be explained, and the description still names the key fields. Combined with the routing guidance and free-tier note, an agent has everything needed to select and invoke this tool 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?

Zero parameters, so the baseline is 4; the description confirms 'takes no arguments', removing any ambiguity about whether inputs are expected. Nothing more can be added for a parameterless tool.

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+resource ('Get the grading rules themselves') and enumerates the content precisely: grade requirements for A/B/C/F/Unknown, freshness derivation, Unknown handling, and the independence guarantee. It also explicitly names the sibling it is not (pulse_lane_detail), so an agent can separate the policy tool from the per-lane verdict tool without reading 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 both sides of the routing decision: use it to explain or defend a grade to a human, or to interpret the grade filter on pulse_lanes; use pulse_lane_detail instead for a specific verdict. The condition selecting the alternative is named, not implied.

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 nonetheless adds real operational context: it works without an API key on the free tier, returns a verdict block for graded lanes, and refuses an unknown slug with an error naming it. Return-format detail is somewhat redundant with the 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?

Front-loads the purpose, then routing guidance, then behavioral facts, then return/error behavior. Efficient and well ordered, though the field enumeration and return details are slightly dense for a one-parameter lookup.

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

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

For a single-slug read tool with full annotations and an output schema, the description covers purpose, routing, auth tier, error behavior, and the odd verdict-block return. 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 there is a single parameter, so the schema fully documents the slug and its exact format. The description adds no syntax or constraint beyond 'one resource', 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 (Get) and resource (full directory record for one resource) and enumerates the returned fields (description, kind, capabilities, tags, pricing flag, stars, links, source). It explicitly distinguishes itself from pulse_resources and pulse_lane_detail, so an agent can route without opening schemas.

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 an explicit trigger ('Use after pulse_resources when you have chosen an entry and need its links or metadata') and an explicit exclusion with the named alternative ('do not use it for work lanes you want to judge (use pulse_lane_detail)'). Both when-to-use and when-not-to-use are covered.

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 the description still adds genuinely new behavioral facts: it works without an API key on the free tier, filters combine with AND, and invalid kind/sort/arguments are refused with the accepted values rather than silently ignored. That error-handling contract is exactly the kind of trait an agent cannot get from 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?

Well front-loaded: purpose, then routing to siblings, then combination semantics and safety. Slightly over-packed — the 'Returns {count, kinds, resources[]}' clause duplicates the existing output schema and could be dropped without loss.

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

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

For an 8-parameter, zero-required search tool with full schema coverage, enums, and an output schema, the description covers purpose, routing, filter combination, auth/free-tier behavior, and failure mode. Nothing an agent needs 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%, so the baseline is 3, but the description adds the cross-parameter semantics the schema cannot express: 'Filters combine with AND' and 'omit all to list everything'. It does not add per-parameter syntax beyond the schema, so it falls short of a 5.

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 the agent directory of models, MCP servers, frameworks...') and immediately scopes the sibling set by naming pulse_resource_detail and pulse_lanes with the conditions that select them. An agent can route correctly without opening any 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 concrete use cases ('free open-source MCP servers with 1000+ stars', 'models that do video-gen'), explicitly excludes the two nearest alternatives by naming them, and states the degenerate case ('omit all to list everything'). Nothing 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?

Adds real behavior beyond the annotations: works without an API key on the free tier, an unknown lane is refused with an error naming it, and the recommendation reflects observed outcomes within the snapshot window rather than a guarantee. Repeating 'Read-only and idempotent' is redundant given readOnlyHint/idempotentHint, and enumerating the return shape is partly redundant with the output schema, so it stops short of 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?

Front-loaded with the decision and its output set, then prerequisites, then caveats; each sentence mostly earns its place. The return-shape enumeration duplicates the output schema and the read-only/idempotent line duplicates the annotations, costing a little tightness.

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?

Covers the prerequisite chain, the semantics of ambiguous outputs ('Unknown means unmeasured rather than failed'), error behavior, and the non-guarantee framing. With an output schema present, the description does not need to explain return values yet still clarifies their interpretation, so nothing an agent needs 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?

With a single parameter at 100% schema coverage the baseline is already 3-4, and the description adds the provenance of the value ('the slug, exactly as returned in the slug field of pulse_lanes'), telling the agent where to source it. No format or validity nuance beyond that.

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 ('evidence-backed recommendation on whether an agent should spend attempts on a lane') and enumerates the exact possible outputs. It explicitly differentiates itself from siblings by naming pulse_lanes as the prerequisite and pulse_lane_detail as 'the audit trail behind it', so an agent can route correctly without opening any 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 an explicit ordering rule ('Call pulse_lanes first to get the slug, then call this before committing an agent's time'), names the alternative decision tool and its role, and states the exclusion implicitly by framing this as the decision tool versus detail's audit role. Nothing 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 readOnly, idempotent and non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: no API key required on the free tier, zero arguments, and the shape of the response (flat object with snapshotAt, methodologyVersion, etc.). It stops short of noting rate limits or caching of the snapshot, which would have made it 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?

Purpose and the returned figures are front-loaded, followed by usage and routing guidance. The long enumeration of metrics is justified because it tells the agent what it can quote, though it could be tightened with a grouping phrase.

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 description need not document return values in full, yet it still names the key fields. It covers when to call, what it returns, auth requirements, and the sibling alternative — nothing material is missing for a zero-argument read 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?

The tool takes no parameters, so the baseline is 4 per the rubric. The description confirms this explicitly ('Takes no arguments'), which is the only param-related thing an agent needs to know.

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 ('Get the index's headline numbers') and enumerates exactly which figures are returned, including the snapshot date. It also explicitly distinguishes itself from the sibling pulse_lanes, so an agent can route between them 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 three concrete use cases (sizing the index, quoting a dated figure, checking data freshness before trusting a grade) and names an alternative tool with the condition that selects it ('use pulse_lanes when you need the lanes themselves'). Nothing 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.