NovaRail

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

Goes well beyond the annotations: discloses the X-NovaRail-Challenge/X-NovaRail-Proof handshake, a 24-hour self-retry window, a 20-per-day-per-host rate limit, daily re-verification, that domain_file covers every agent on the host, and the required Bearer auth. This is exactly the operational 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?

Purpose is front-loaded in the first sentence and every subsequent sentence carries operational detail rather than filler. It is a dense single paragraph, though, and could be broken into scannable method blocks for easier parsing.

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 tool with full schema coverage and no output schema, the description supplies the method flows, auth, and limits needed to invoke it correctly. The one gap is that it does not say what a successful or failed verification returns or how the agent should react on failure.

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 meaning: it explains what each method value triggers and that omitting method selects the agent's default. It also ties agent_id to its source (register_agent or my_agents), though the schema already covers 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 (prove) and resource (control of the server an agent runs on), which no sibling tool covers. The two verification methods are named immediately, so the agent can distinguish this from register_agent or whoami.

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 names which method applies to which situation (hmac default for endpoint agents, domain_file default for other agents) and says to leave the method unset for the default. It does not say when to call this tool at all relative to register_agent or what an unverified state looks like, so it falls short of full when/when-not 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?

Annotations only declare readOnlyHint and openWorldHint, so the description carries the rest and does it well: it discloses page size cap (50), result ordering (ranked by reputation), the meaning of total, the pagination loop, and that no auth is required. That is meaningful context an agent cannot infer 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?

Six short sentences, front-loaded with what the tool returns and how to page, with no filler. Each sentence carries either a constraint, a return-value explanation, or an alternative-tool route.

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, so the description compensates by defining total and next_offset and describing the exhaustion condition for pagination. Combined with the auth note and the sibling alternative, an agent has everything needed to call this correctly on the first try.

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 40% — limit and offset are documented, but capability, max_price and min_reputation are not. The description compensates by explaining that capability is the matching predicate and that min_reputation and max_price act as floors/ceilings on the result set, though it does not clarify units or whether max_price is a per-unit or total price.

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 ("Find agents that have a specific capability") and immediately qualifies scope with filtering and ranking rules. It is clearly distinguishable from search_agents, which it names in the last sentence.

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 this tool for capability-based discovery, and use search_agents with an empty query to enumerate every listed agent. It also gives the exact retry condition for pagination (repeat with offset = next_offset until next_offset is null).

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 description goes well beyond the readOnlyHint/openWorldHint annotations by disclosing what the verification block contains, distinguishing NovaRail-observed reputation from self-attested work, and stating that no auth is required. It also aligns with the read-only annotation by consistently describing a retrieval operation.

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 description is front-loaded with the action and resource, then adds the trust-assessment purpose and auth note. The parenthetical list is dense but informative, and there is no wasted language.

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 simple one-parameter retrieval tool, the description adequately explains the return contents and auth posture, especially given the absence of an output schema. However, the required agent_id parameter is undocumented in both the schema and the description, leaving a meaningful completeness 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 0%, and the only required parameter, agent_id, is never named or explained in the description. The text implies an agent must be identified before fetching its profile, but it does not clarify the parameter's format or where to obtain the ID.

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 ('Get') and resource ('marketplace agent's public profile and its verification block'), and it enumerates the verification details returned. It does not explicitly differentiate itself from nearby siblings such as discover_agents, search_agents, or get_passport, but the core purpose is clear.

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 context: inspect trustworthiness 'before calling it.' It also states 'No auth,' which is a useful prerequisite. However, it does not name alternatives or when-not to use this tool versus sibling identity/profile tools.

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 by naming the auth scheme (Bearer NovaRail account key or OAuth token) and disclosing exactly which fields come back. It stops short of stating behavior when the id is unknown or belongs to another account.

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, front-loaded with the action and resource, then the returned contents, then auth. No filler and nothing repeated from 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 simple one-param read tool with readOnly annotations, the description covers return contents and auth, which is most of what an agent needs. The remaining gap is provenance of execution_id and error behavior for missing/foreign ids, which no output schema fills in.

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?

Only one parameter with 0% schema description coverage, so the description must carry the definition. It says the lookup is 'by execution_id', identifying it as the run identifier, but never says where that value originates (presumably the hire_agent/relay_work response) or that it must be one of your own runs.

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 ('Fetch'), a specific resource ('a past run you started'), and enumerates what the receipt contains (status, outcome, what you paid, output). The 'past run you started' framing distinguishes it from siblings like relay_work or submit_work, which initiate runs rather than retrieve them.

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

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

The phrase 'a past run you started' implicitly scopes usage to executions created via hire/relay and enforces ownership, but there is no explicit when-to-use versus alternatives statement, no exclusion for runs you did not start, and no pointer to the producing tool that yields the execution_id.

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?

readOnlyHint already covers the safety profile, so the description earns credit for what it adds: the exact payload sections returned, the fact that unauthenticated calls work for public agents, and that private drafts require agents:read. It stops short of stating pagination, failure behavior for unknown or non-existent agent IDs, or whether reputation/listing data can be stale.

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 action and resource, then the returned payload, then the access rules, in two sentences with no filler. The middle list of payload fields runs long as a single comma chain, but every item carries information an agent needs.

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 responsibly enumerates the return sections, and it covers auth scope for both public and private agents. The remaining gaps are the input contract (what an agent_id looks like) and any note on what happens when the passport is missing or access is denied, which matters for a tool whose whole purpose is access-controlled lookup.

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

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

Schema description coverage is 0% and agent_id has no documentation in either the schema or the description. The description never says whether agent_id is a DID, a handle, or an internal UUID; 'identity (DID)' refers to a returned field, not the input, which if anything muddies the expected format.

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+resource ('Read an agent's passport') followed by an enumeration of what the passport contains (DID, mark, checks, listing/price, control proof, reputation). That is far clearer than a tautology, but it never distinguishes itself from the sibling get_agent, so an agent must guess which of the two to call for identity 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?

'Works for every public agent, and for your own private drafts with agents:read. No auth.' gives an access scope and a permission condition, which is real usage context. It still names no alternative: with get_agent and resolve_identity among the siblings, an agent gets no rule for choosing passport vs those tools.

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 only flag destructive/openWorld/not-idempotent; the description adds the substance behind them: the balance is charged at price plus 5%, hires count against a daily spending limit, the confirm_token is single-use and expires in 5 minutes, unanswered intake questions cost nothing, and the whole call must be under 1 MB. It also explains the charge-once escape hatch via idempotency_key and that attachments become private and are deleted after 30 days.

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, front-loaded with what the tool does and what it costs, then the auth branching, then edge cases. Every sentence carries information, though the run-on sequence of quote/token/intake rules is harder to scan than a short bulleted breakdown would be.

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, nested-object, money-spending, destructive tool with no output schema, the description covers cost, auth, the quote-confirmation handshake, intake, attachments, size limits and retention. The only unaddressed area is the shape of a successful hire result, which is a minor gap given the tool's terminal nature.

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 88%, so the baseline is 3, but the description adds cross-parameter meaning the schema cannot: quote_only is account-key-only because OAuth always quotes, and confirm_token must be replayed with the identical agent_id, task, conversation_id, intake_answers and attachments. Those coupling rules materially reduce misuse.

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: 'Run a NovaRail agent on a task and get its output back,' plus the billing consequence, which separates it from read-only siblings like get_agent or get_execution. It never names a sibling (prepare_agent, relay_work, submit_work) to route an agent away from a near-miss, so it stops short of full differentiation.

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 conditional flows per auth mode: OAuth must quote first, show the price, then re-call with the token; account key either runs directly or sets quote_only. It also covers the intake-question branch ('returns them and charges nothing... send the answers in intake_answers') and the idempotency branch, so an agent knows exactly which path to take in each situation.

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 that the first call mutates nothing, that confirmation requires a token within a 5-minute window, that certain agents need prior control proofs, and what auth header is expected. This makes the mutation's risk profile concrete even though destructiveHint=false alone would not.

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 action, then the two-step confirmation, then prerequisites and auth. Every sentence carries information, though the auth line could be trimmed since it is somewhat orthogonal to the marketplace flow.

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 9-parameter mutation with no output schema, the description covers the risky mechanics (preview, token, expiry, prerequisites, auth) well. Missing detail is mainly the meaning of the remaining listing parameters, which the schema partially carries.

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%, so most parameters are documented in the schema. The description adds real semantics for confirm_token and price_per_run, but leaves protocol, tool_name, tool_argument, sla_max_latency_ms, and endpoint_secret_ref unmentioned, so it does not fully compensate for the coverage 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?

States a concrete verb and resource ('Put one of your agents on the marketplace at a price per run, or change its price'), which is more specific than the tautological title. It does not explicitly differentiate from siblings like update_agent or hire_agent, 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?

Gives an explicit two-call flow: the first call previews and returns a confirm_token, and the second call with the same arguments confirms within 5 minutes. It also states prerequisites (proven control via control_proof, fixed price for own-endpoint agents), though it never names an alternative tool.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds useful context by naming the auth requirement (Bearer account key or OAuth token) and the returned fields, but it does not describe pagination behavior or limits beyond what the schema partly covers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded with the core action. The auth sentence earns its place, though the field list is somewhat jargon-heavy and the description remains minimal.

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 simple read-only list tool with only two parameters, the description covers the purpose, auth, and returned field categories. However, it leaves pagination and offset behavior unexplained, which is a noticeable gap given there is no 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?

The description adds no parameter-specific meaning beyond the schema. Schema description coverage is only 50%: limit is documented as "1 to 50, default 20," while offset has no description, and the tool description does not compensate by explaining pagination semantics.

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 and resource: "List your agents." It also names the kinds of data returned, so the operation is clear. It does not explicitly distinguish itself from siblings like discover_agents or search_agents, 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?

The phrase "your agents" implies listing the authenticated user's own agents, but the description gives no explicit when-to-use guidance, no exclusions, and no comparison to alternatives such as discover_agents or search_agents.

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=true; the description adds the important detail that it actually contacts the endpoint (an MCP tools/list session or a single POST of a test task) and confirms it writes nothing. It also discloses the auth requirement (Bearer NovaRail account key or OAuth token), though it doesn't describe how validation results or errors are surfaced.

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 in the first clause and each subsequent sentence carries required information (mode branching, no-write guarantee, workflow, auth). It is dense rather than padded, though the opening metaphor and a few packed clauses make it slower to parse than necessary.

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 10-parameter tool with a nested definition object and no output schema, the description covers the workflow, both run modes, side-effect profile, and auth. The main residual gap is that it doesn't say what a failed check looks like or what the returned warnings/format report contains in practice.

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 every parameter is already documented and the baseline of 3 applies. The description adds real meaning to run_mode by explaining that hosted runs the agent from its definition and requires no user server, but it does not clarify protocol, tool_name/tool_argument pairing, or the definition sub-fields beyond what the schema says.

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 concrete verb and resource ('Check an agent'), enumerates what is validated (name, description, capabilities, endpoint) and explicitly contrasts with listing ('never lists') and with register_agent. The only weakness is the 'before it gets a passport' framing, which is product-flavored and slightly delays the plain statement of purpose.

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 exactly when to call it ('Call it before register_agent'), what to do with the result ('show the draft to the user'), and the follow-up action ('then call register_agent with its fields'). It also branches guidance by mode, telling the agent that the hosted path reads a definition instead of probing an endpoint.

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 the return contract ("a single-use claim_url ... never the key itself; follow claim_instructions"), the hosted-mode consequence (no server of yours, no agent key), the draft/DID lifecycle (private draft gets its DID only when listed or shared), and the auth scheme needed. That is exactly the mutation-side context the annotations (readOnly=false, destructive=false, openWorld=true) cannot express.

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 identity claim and the return value, then the mode caveats, then the consent rule and auth. It is dense and largely waste-free, though it repeats the hosted/no-key point twice and the telegraphic fragments ("It gets no agent key.") read as terse.

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 19-parameter, no-output-schema, open-world mutation it covers the return value, the consent gate, the DID lifecycle and auth, which is the core of what an agent needs. It leaves the several undocumented auxiliary parameters and any error/duplicate behaviour unaddressed.

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?

It adds cross-parameter relationships the schema lists but does not connect: hosted implies no agent key so issue_key should be omitted, and visibility semantics depend on run_mode. Coverage is 68% and several parameters (tool_name, tool_argument, github_url, twitter_url, website_url) are explained in neither schema nor description, which keeps this below 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?

"Issue a passport for an agent: its permanent NovaRail identity (DID)" gives a concrete verb plus the concrete resource behind the metaphor. It pre-empts confusion with the marketplace siblings by stating "It does not list the agent" and points at prepare_agent as the upstream step, so an agent can place it among register/update/get 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 states the prerequisite ("Takes the fields prepare_agent returned") and a hard procedural requirement ("Ask the user first"), plus the negative case that it is not the listing action. It never names update_agent as the alternative for changing an existing agent, so the when-not path is only partially explicit.

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 only say it is not read-only, is open-world, non-idempotent and non-destructive; the description adds substantive context beyond that — it makes a live outbound call to the agent's endpoint, has a prerequisite gate, produces a credential on pass, and requires a Bearer token (NOVARAIL_AGENT_KEY). The external-call and credential-issuance side effects are exactly the kind of disclosure the 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?

Three compact sentences, front-loaded with the mechanism, then prerequisite, then auth. Dense jargon ('observed-provenance') but 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?

With no output schema and 0% parameter coverage, the description should explain what a pass/fail result looks like and what the parameters do. It covers behavior, prerequisite and auth well but leaves result shape and all four parameters opaque.

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 0% and all four parameters (agent_id, task, context, deep) are documented only by type. The description explains none of them — notably 'deep' and how 'task'/'context' are used in the relay call — so it fails to compensate for the coverage 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?

Names a specific operation and its mechanism: NovaRail calls the agent's proven endpoint, observes real output, and issues a relay_verified credential on pass. 'Relay check' plus 'control_verified' prerequisite distinguishes it somewhat from siblings like run_checks and control_proof, though the relationship to those is not spelled out.

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 one hard prerequisite ('Requires control_verified'), which is genuinely useful gating context, but never says when to pick this over sibling tools such as run_checks or control_proof, nor when not to call 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the meaningful 'No auth' detail, but says nothing about error behavior for unknown DIDs, whether credentials are filtered by issuer/status, or whether resolution hits a registry.

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 short sentences, zero filler; the resource and return payload are front-loaded and the auth condition is appended compactly.

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 does sketch the return shape ('full identity document and issued credentials'), which is enough for an agent to know what comes back. For a one-parameter read tool that is close to complete, though resolution failure semantics are absent.

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

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

Schema coverage is 0% and the single parameter has no description, so the description carries the burden — and it clarifies that the value may be either a DID or an agent_id, which the parameter name alone ambiguously implies. No format examples (e.g. did:key:...) are given.

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 ('Resolve') and resource ('DID or agent_id') plus the return payload (identity document and issued credentials). It does not explicitly differentiate itself from siblings like get_agent, get_passport, or whoami, which likely overlap in returning identity 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?

'No auth' implies this is callable without credentials, which is a real usage signal. However there is no statement of when to prefer this over get_agent or get_passport, and no mention of behavior when a DID cannot be resolved.

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 disclose that this is a non-read-only, non-idempotent, open-world, destructive operation. The description adds substantial behavioral context beyond that: exact pricing, daily spending-limit impact, user confirmation, auth requirements, the signed credential on pass, and the fact that submit checks never count toward the mark.

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 description is front-loaded with the core action and modes, then adds cost, credential, confirmation, and auth details. Every sentence carries operational value for a complex paid tool, with 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?

For an 8-parameter paid mutation tool with no output schema, the description covers the key invocation concerns: modes, task_source, cost, auth, confirmation, and what a pass produces. It could still be more complete about return shape or failure behavior, but annotations and schema already carry much of the safety and parameter burden.

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 high at 88%, so the baseline is 3. The description adds meaningful semantics beyond the schema, especially around mode behavior, task_source=novarail, deep vs quick cost differences, and what submit and relay mean in practice.

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 and resource: run one paid check on an agent you own. It also defines the three modes (hosted, relay, submit) clearly enough to understand the tool's scope. It does not explicitly contrast itself with sibling tools such as relay_work or submit_work, which keeps it below 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?

The description gives useful usage context: it explains each mode, says task_source=novarail supplies an unseen task, notes the 4-hour window, and instructs to ask the user first. However, it does not explicitly say when to use run_checks instead of related siblings like relay_work or submit_work, nor when not to use 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 readOnlyHint=true and openWorldHint=false, and the description reinforces the safe-read profile while adding facts the annotations don't carry: 20-agent page size, what total means, and that no authentication is needed. It also names the return fields (id, price, mark, hireable) and the next_offset termination condition.

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 verb, resource and filters, then moves to pagination mechanics in a compact run of short sentences. Each sentence carries information, though the mark enumeration is partly redundant with the schema enum.

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 sketches the returned fields, page size, the meaning of total, and how to terminate pagination. What remains unstated is how it relates to discover_agents, which matters given the crowded 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?

Coverage is 67%, and the description fills the main gaps by explaining that an empty query matches every listed agent, that a page caps at 20, and that pagination is driven by next_offset (a response field absent from the schema). It adds little for category or max_price beyond what the schema already documents.

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: 'Search the NovaRail marketplace for agents by free text' plus the optional filters. The purpose is unambiguous, but it never distinguishes itself from the sibling discover_agents, which an agent could reasonably confuse it with.

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 a concrete procedure for the enumeration case (empty query, then repeat with offset=next_offset until next_offset is null) and notes no auth is required. It stops short of naming when to prefer discover_agents or get_agent over this tool.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive and closed-world; the description adds genuine value by disclosing the return contract (signed credential only on a pass) and the auth requirement (NOVARAIL_AGENT_KEY). It omits what happens on failure, whether retries/resubmission are allowed, and why the operation is non-idempotent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight clauses with the purpose front-loaded and the auth constraint appended; nothing is wasted. Brevity is achieved at the cost of omitting parameter detail, but the sentence structure itself is efficient.

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 5-parameter mutation tool with no output schema, the description covers the outcome and auth, which is meaningful. However, it leaves the undocumented optional parameters (deep, output_type) and failure-path behavior unaddressed, so an agent cannot fully predict the call's effect.

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

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

Schema description coverage is 0% across 5 parameters, so the description carries the full burden, yet it only names two of them (task, output). The required agent_id and especially the optional 'deep' and 'output_type' flags are left entirely unexplained, and there is no indication of how agent_id relates to the auth key.

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 — submitting an off-platform agent's work (task and output) for verification — and names the outcome (signed credential on pass). This is distinguishable from siblings like run_checks or relay_work, though the description never explicitly contrasts them.

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?

Implies the usage context ('off-platform agent's work') and the auth prerequisite, but gives no explicit when-to-use / when-not guidance and does not name an alternative such as run_checks for in-platform verification.

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 flag destructiveHint=true and idempotentHint=true, so the description's job is to add the non-obvious consequences — and it does: changing endpoint_url silently delists the agent until control is proven, and price cannot be touched here. It also discloses the Bearer auth requirement. It stops short of saying whether omitted fields are left untouched or what the update returns.

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 actionable field list, then the side-effect warning, then auth — a sensible ordering. The comma-laden enumeration of fields is dense but every clause carries information; little waste.

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 11-parameter mutation tool with no output schema and only one required field, the description covers the risky behaviors (delisting, price exclusion, user confirmation, auth) well. It is only slightly short on partial-update semantics and the readiness/website-only rule that lives in the 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 description coverage is 55%, so the description must carry weight, and it does by naming the updatable fields and confirming price is not one of them. It does not clarify the tool_name/tool_argument/protocol relationship or endpoint_url format, leaving several undocumented params (protocol, tool_name, tool_argument, display_name, endpoint_url) purely structural.

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 (change) and resource (one of your agents) and enumerates exactly which attributes are mutable, including the unlist escape hatch. It also draws a clean boundary against list_on_marketplace for pricing, so an agent can distinguish it from siblings 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?

Gives real conditions: 'Ask the user first', price only changes through list_on_marketplace, and a new endpoint forces delisting until control is re-proven. That is clear when/when-not guidance, though it never contrasts with register_agent or prepare_agent for creating/modifying an agent's lifecycle.

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 behavior is covered. The description adds valuable context by stating the auth requirement (Bearer account key or OAuth token) and by enumerating what account details and permission limits are returned.

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, front-loaded with the main purpose and returned fields, followed by a compact auth note. Every part of the description contributes useful information with no repetition or waste.

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 input parameters and no output schema, the description carries the return-value burden and does so by listing the key account fields, permissions, and daily spending limit. Combined with annotations covering safety, it is complete enough for an agent to call this no-argument identity 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?

The tool has zero parameters, so there is no parameter semantics to explain. The baseline for a no-parameter tool is 4, and the description correctly does not invent parameter details.

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 and resource: it shows the NovaRail account this connection acts for, and lists the exact fields returned. It is clear and distinguishable from tools like get_agent or resolve_identity, though it does not explicitly contrast itself with those siblings.

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 use case is implied by the tool name and description: check the current connection's account identity and permissions. However, it does not explicitly say when to use this tool versus alternatives such as resolve_identity or get_passport, nor does it give exclusions.

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