Machine Relations Index

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint false), so the bar is lower. The description still adds real behavioral content: it discloses the evidence-state vocabulary returned per question type ('published with rates, collecting, or not collectable'), which is not derivable from any structured field.

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 stating the return payload, with the enumeration folded into a parenthetical rather than expanded into prose. Dense but every clause carries content; only minor cost is the long inline list.

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 and only one param, the description does the heavy lifting by describing the return shape: the set of question shapes and the three evidence states. It stops short of explaining what a rate looks like or any pagination, but it is sufficient for an agent to call this correctly and interpret the result.

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% with a single required 'category' key, and the schema already supplies the format hint and the cross-reference to mri_list_categories. The description adds no further parameter meaning, 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?

Specific verb ('Return') plus resource ('one category's question shapes') and an enumerated list of the shape types it covers (best tools, comparisons, top lists, etc.). It is clear what the tool yields, though the description itself never names the sibling tools it is distinct from (mri_list_categories / mri_get_domain), so differentiation is left to the 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?

No explicit when-to-use or when-not-to-use statement. The sequencing is only implied by the parameter's schema note ('Category key from mri_list_categories'), which tells the agent this follows a listing call, but the description offers no exclusions or alternatives.

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 traits (readOnly, idempotent, non-destructive, closed-world), and the description adds useful behavioral context: the rate is pooled across engines and not split by engine, and it names the returned metrics and source-role taxonomy. It does not discuss freshness or pagination behavior, so it is strong but not exhaustive.

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 and the description uses only three sentences. The first sentence is dense with parenthetical metric and source-role details, but the content is relevant and there is little wasted space.

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 six-parameter tool with no output schema, the description does well by explaining the returned metrics, source-role taxonomy, and pooled-across-engines scope. It could be more complete by explaining pagination/default limit behavior and the source_role filter, but the core information an agent needs 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 67%, and the schema already documents category, question_shape, cursor, and source_role. The description defines citation rate and enumerates source roles, but it does not clarify the limit/offset/cursor parameters or explicitly frame source_role as a filter, so it adds only moderate meaning 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 resource (ranked source domains cited by AI answer engines) and scope (one category and question shape, pooled across engines). It explicitly distinguishes the tool from mri_get_engine for per-engine data, so an agent can identify its purpose without opening the 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 a clear usage boundary: this tool returns pooled data and is not split by engine, while mri_get_engine should be used for one engine. That is an explicit alternative and selection condition, leaving little ambiguity for the main usage decision.

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, so the safety profile is covered. The description adds real behavioral context beyond that: it explains what 'runsCited 0' means and explicitly warns that byEngine is the whole window, not a rate inside a single category — a non-obvious interpretive rule. It omits auth, rate limits, or freshness of the window, keeping it from 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?

Front-loads the core return contract before the usage examples and caveats, and every clause carries information. It is somewhat dense as one long paragraph, which makes it slightly harder to scan than a bulleted breakdown.

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?

No output schema exists, so the description must carry the return shape — and it does: overall rate, per-engine cited/observed runs and evidence-floor flag, confidence tier, ranks overall and by source role, and per-category segments. Combined with the byEngine caveat, an agent has everything needed to call and interpret it.

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 'domain' parameter is fully documented in the schema, including that a URL is accepted. The description restates 'one domain or URL' without adding format, normalization, or error-handling detail beyond what the schema provides, 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 and resource: for one domain or URL, returns how often AI answer engines cite it, then enumerates the returned measures. This clearly separates it from siblings like mri_get_cited_sources (which lists sources) and mri_get_engine (engine-level data).

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 triggering questions ('does ChatGPT cite <site>', 'what share of Perplexity runs cite <site>'), which is strong context for selecting this tool. It stops short of naming an alternative tool for adjacent questions, so routing between mri_get_* siblings still requires 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 cover safety (readOnly, idempotent, non-destructive, closed-world), and the description adds genuinely non-obvious behavior: the rate is computed over the whole window and stays whole-window even when a category filter is applied, and results are suppressed for entities below the evidence floor. It does not mention pagination behavior, though the cursor/offset precedence is documented in the 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 definition and ordering metric, then the category caveat, then call examples — a sensible priority order with no filler. The evidence-floor sentence is slightly awkwardly phrased ('Collecting categories and engines ... withhold the ranking') but still carries 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?

No output schema exists, and the description covers the essential contract: what is ranked, by what metric, and how filtering affects the metric. Ordering direction (descending by rate) and the shape of each result row are inferred rather than stated, which is the main residual 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 60%, with engine, cursor and category documented. The description adds real meaning the schema does not: category narrows which sources appear while the ranking metric remains whole-window, and engine is implicitly tied to the mri_list_engines key set. limit and offset carry no semantics in either place.

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 resource (ranked sources), the scoping dimension (one answer engine), and the ordering (that engine's citation rate across the window). It is distinguishable from the list/domain siblings by scope, but it never names or contrasts with mri_get_cited_sources, which sounds closely related.

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 closing sentence gives concrete triggering questions ('what sources does Perplexity cite most?', 'which sources does Google AI Overviews cite among published <category> sources'), which maps intent to tool. It also states a when-not condition — rankings are withheld below the evidence floor — but offers no explicit alternative tool for the related cited-sources use case.

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 openWorldHint=false, so the safety profile is covered. The description adds that only categories with *published* citation rates appear (a meaningful scoping trait) but says nothing about result size, 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?

Two sentences, no redundancy: the first defines content and payload, the second gives the call-ordering instruction. The most actionable line (call this first) is front-loaded in the second position where it is not buried.

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 burden of describing the return payload and does so (categories, question shapes with citation rates, source-role vocabulary). For a zero-required-parameter list tool this is nearly complete; only ordering/volume of results is left implicit.

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 `release` parameter is fully documented in the schema, including the release_unavailable failure mode. Baseline 3 applies; the description adds no parameter semantics of its own.

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 (List) and resource (Machine Relations Index categories), then enumerates what each entry contains (question shapes with published citation rates, source-role vocabulary) and gives concrete example keys. This is clearly distinguishable from the mri_get_* siblings, which retrieve a single category, domain, or engine.

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?

"Call this first to get a valid category key" gives explicit sequencing and the reason for calling it, which routes the agent ahead of mri_get_category and the other getters. It stops short of naming alternatives or stating when-not to use it, so it falls just under the top band.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description adds genuine context the annotations cannot: the scope is 'across the whole window' and rows are annotated with an evidence-floor verdict. It omits ordering, whether the roster is exhaustive, and failure behavior (the schema, not the description, carries release_unavailable).

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 that opens with the action and then enumerates returned fields, with essentially no filler. It is somewhat run-on — five distinct return attributes chained with commas — which costs a point against a crisper list form.

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 full burden of describing return values, and it does so thoroughly (model, runs, days, evidence-floor pass/fail, top cited source). Annotations cover the safety profile and the schema covers the one parameter. Only ordering and result-size behavior are left unstated.

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 sole 'release' parameter is fully documented in the schema, including the release_unavailable consequence for non-current releases. The description adds nothing about the parameter, so the baseline 3 applies; it neither compensates nor detracts.

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 uses a specific verb ('List') and resource ('each answer engine') and enumerates exactly what each row contains: model, observed runs and days, evidence-floor status, and most-cited source. This is far more than a restatement of the name. It stops short of 5 because it never distinguishes itself from the singular sibling mri_get_engine, leaving the agent to infer that this is the enumerate-all variant.

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?

There is no explicit when-to-use or when-not-to-use statement, and no mention of the obvious alternative mri_get_engine for a single engine or mri_list_categories for the category axis. The only implied guidance is that listing 'each' engine means an unfiltered enumeration, which the agent must derive on its own.

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