Spillmark

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description goes beyond that by disclosing what comes back — a brief method summary, links to the full method, and a sample report — and crucially warns that the sample report uses made-up numbers, preventing an agent from treating those figures as real results.

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 front-loaded sentence with no filler, covering what the method addresses and what the response contains. The phrasing 'the sales Meta ads cause on Amazon' is slightly dense but still readable.

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, no-output-schema informational tool, the key missing piece would be what the caller receives, and the description states exactly that (method summary, links, sample report) plus the caveat about fictional numbers. Nothing an agent needs in order 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The description correctly implies no input is needed.

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 content resource: an explainer of Spillmark's geo-holdout lift methodology (Meta ads → Amazon sales), plus links to the full method and a sample report. An agent can tell this is a documentation/lookup tool rather than a computation tool. It does not explicitly contrast itself with run_calculator or list_calculators, which keeps it from a 5.

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: an agent infers it should call this when it needs to explain or understand how lift is computed. There is no explicit 'use this when…' statement, no mention of when not to use it, and no pointer to run_calculator for actually computing a lift.

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=true and openWorldHint=false, so safety is covered. The description adds real value beyond that by disclosing what each catalog entry contains (inputs and example values), which tells the agent what a call returns even without an 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, zero filler: the catalog contents come first, the routing hint second. Every clause earns its place.

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 one-optional-param, read-only list tool with no output schema, the description covers scope, contents, and the follow-up action. Only the filtering behavior (what 'q' matches) is left implicit, a minor 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 description coverage is 100% and the single 'q' parameter is documented in the schema with an example ('holdout', 'fees'). The description adds no filtering guidance of its own, 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?

States a specific verb and resource ('List ... free Amazon and Meta ads calculators') and enumerates the items returned (holdout test size, incremental ROAS, break-even ROAS, ACoS, TACoS, fees, LTV/CAC). This makes it unmistakable from siblings how_lift_is_calculated and run_calculator.

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?

Explicitly routes the agent: 'Use run_calculator to run one,' making the list-vs-execute split clear. It doesn't address how_lift_is_calculated or when to prefer browsing over filtering, so not a full 5.

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 declare readOnly and closed-world, and the description is consistent with both while adding real substance: the exact return payload (headline, supporting figures, reading, link) and the silent fallback to example values for missing inputs — a default an agent could otherwise misread as an error.

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?

Four dense sentences, front-loaded with purpose and return shape, then the default-behavior and input-format caveats. No filler and no 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?

Covers discovery (list_calculators), invocation defaults, unit conventions for the two ambiguous input kinds, and the response shape. With no output schema present, naming the returned fields is exactly the gap the description needed to close.

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 would be 3, but the description earns extra credit by documenting the free-form `inputs` map's conventions: percents as points (15 = 15%) and choices as option index. Those conventions are invisible in the schema, where inputs is just an anyOf of number/string/null.

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 ("Runs one calculator from list_calculators on your numbers") and enumerates exactly what comes back: headline result, supporting figures, a one-sentence reading, and a share link. The reference to the sibling list_calculators makes the slug provenance 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?

Explicitly routes the agent to list_calculators for the slug and states what happens when inputs are omitted (example values are used). It does not name a when-not-to-use case or an alternative execution path, but with only two other siblings there is no real competing tool to disambiguate.

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