Robot Skill Hub

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile needs no restatement. The description adds genuinely useful behavior: results distinguish prepared recipes from upstream references, a match is not runtime verification, and empty results come with recovery suggestions.

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?

Roughly five short sentences, front-loaded with what the tool is for and the sibling alternative before query tips. Dense but each sentence carries distinct information; 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, the description usefully explains what results mean (recipe vs upstream reference, not runtime verification) and covers empty-result recovery. It omits pagination behavior despite limit/offset params and doesn't state defaults, which is 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 only 14% across 14 params, so the description carries a heavy burden and only partially meets it — it clarifies q usage and query_mode=task semantics and implies runtime/robot act as filters, but 12 params (os, kind, limit, offset, hub_commit, architecture, etc.) get no semantic guidance such as exact vs prefix matching.

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 the tool's role as broad robotics source/reference discovery or a small candidate-only list, which is clear enough to separate it from start_robot_task. It lacks a crisp verb+resource phrase of its own (the name carries 'find'), but the scope and result nature are stated.

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 names the alternative explicitly (“prefer start_robot_task”) along with the selecting condition (executable starting point with prior fixes and setup argv). It also gives query-shaping guidance (short keywords vs query_mode=task with runtime/robot filters) and instructs following recovery suggestions after empty results.

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 read-only, idempotent, open-world and non-destructive semantics, so the safety bar is largely met structurally. The description adds a genuinely useful behavioral fact beyond them: reads require no authentication. It does not describe pagination, caching or freshness of the catalog counts.

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 sentences with no filler. The capability scope is front-loaded ahead of the supporting auth detail.

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 what comes back (capability groups, onboarding links, catalog counts) and confirms no auth is needed. Given zero parameters and rich annotations, this is close to sufficient; a note on whether counts are live or cached would complete 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?

The tool takes zero parameters, so there is no parameter semantics to document; baseline is 4. The description does not need to compensate for any schema 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 specific verb ('Read') and a well-enumerated resource (public discovery, preparation, contribution and task-memory capabilities, CLI onboarding links, catalog counts). It distinguishes itself from the skill-oriented siblings implicitly by returning hub-level metadata rather than skill data, but never names those siblings explicitly.

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

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

There is no when-to-use statement, no condition that selects this tool over find_robot_skills or inspect_robot_skill, and no exclusions. The only guidance is the auth note, which is a constraint rather than usage routing.

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

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

Annotations already establish read-only, idempotent, non-destructive, open-world behavior, and the description adds real value: 'no installation or execution is performed', the 'untrusted data' framing for recipe/reference entries, and the exact-version and three-entry limits. These are traits not visible in 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?

The use-condition is front-loaded, but the following sentences are dense and pack multiple clauses (contract vs full, recipe entries, untrusted-data warning, applicability) into run-on phrasing. Every clause is relevant but the structure is hard to scan.

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

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

With no output schema, the description must convey return shape; it does describe contract-vs-full contents and pinned recipe/reference entries reasonably. However, several input parameters and the exact record fields returned remain underspecified for a tool with a nested environment object and 40% schema coverage.

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 only 40%, so the description bears more burden. It meaningfully explains the detail=contract branch, but hub_commit, record_version linkage, and environment filtering semantics are largely left to the schema's own text, so compensation is partial.

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 (inspect) and resource (full record, execution contract, pinned recipe/reference) and situates it after a search result, which distinguishes it from find_robot_skills. It is dense but an agent can tell this is a read/detail tool rather than a search or task-start tool.

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?

Explicit sequencing is given ('Use after selecting a search result') and the branch condition between detail=contract and the default full path is stated, plus 'Check applicability'. It stops short of naming alternatives like find_robot_skills or start_robot_task outright, so it is not a full when/when-not guide.

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/openWorld/idempotent/non-destructive, and the description reinforces rather than contradicts them with concrete scope: "Read-only English lexical matching; no installation, execution or sharing." It also discloses the default response shape (one candidate, source pins, environment, evidence/recall summaries, setup argv) and the contract_url prerequisite — context annotations 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?

The purpose is front-loaded and length is proportionate for a 13-param tool, but the middle sags into tangled fragments: "Use detail=execute for the complete execution contract in this same lightweight response; otherwise read selected.contract_url before execution" requires re-reading, and "detail=full restores the legacy combined view" is changelog residue rather than actionable guidance.

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 partially compensates by enumerating the compact payload and pointing at selected.contract_url. But for a tool with 13 undocumented parameters and two enums, it leaves critical unknowns: what query_mode changes about matching, what the free-text filter params accept, and what the limit maximum of 3 implies for retrieval strategy.

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 13 parameters, so the description must carry the load — but it explains only `detail` (compact/execute/full). The 10+ filter parameters (os, robot, python, runtime, controller, hub_commit, observation, architecture, runtime_version, limit) and the semantically important query_mode enum are entirely undocumented; "Supply only known filters" is cryptic rather than clarifying.

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 outcome: "Find an executable starting point for a robot task," which usefully corrects the potentially misleading name (it does not start anything). It does not, however, differentiate itself from siblings like find_robot_skills or inspect_robot_skill, 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?

The description gives real workflow guidance around the detail modes ("Use detail=execute for the complete execution contract... otherwise read selected.contract_url before execution" and "Read applicable recall details before reuse"). But it never says when to pick this tool over find_robot_skills or inspect_robot_skill, nor when to use query_mode=task vs all_terms, leaving the primary selection decision implicit.

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