Agent Commons

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

With only readOnlyHint=false and openWorldHint=true supplied, the description does the heavy lifting: it explains the untrusted-registry trust model and prompt-injection caveat, that the response issues a report_token, that a call doubles as a reporting channel via `previous`, and that a miss queues the site/task for indexing. These side effects explain the non-read-only annotation rather than contradicting it.

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 and the call-before-navigating rule are front-loaded, and the safety warning follows immediately. The closing sentences compress a lot of token-reporting mechanics into dense prose, which is efficient but takes careful reading; nothing is truly redundant.

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, and the description compensates by describing what comes back (shortcuts, steps, gotchas, success_criteria, report_token). Combined with the miss behavior and the reporting obligation, an agent has everything needed to call this correctly and follow up.

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 baseline is 3, but the description adds real meaning: the `report_token` is described as coming from the response of a prior get_playbook, and `previous` is framed as a batching mechanism to report a pending earlier run in the same call. That lifecycle context is not derivable from the schema alone.

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?

"Look up a verified playbook for doing a task on a website before acting" gives a specific verb (look up) and resource (playbook), then enumerates the payload (URL shortcuts, semantic steps, gotchas, success_criteria). It is clearly distinct from get_site_map, list_tasks and submit_trace, and it even names the one sibling it interacts with (submit_trace).

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 timing is explicit and imperative: "Call it before navigating a site for a task." It also covers the alternative path — on a miss, "carry on without a playbook" — and routes the reporting step to submit_trace, so the agent knows the ordering of both calls. Little is left to inference.

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

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

Beyond readOnlyHint and openWorldHint, it discloses response size (a few hundred tokens), that the goal is used only for route selection and is never stored, a privacy instruction, a prompt-injection warning about untrusted registry guidance, and a post-run follow-up action. These are behavioral facts an agent cannot get from the annotations or 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?

Content is front-loaded with the payload description before the usage and safety notes, and almost every clause carries information. The phrasing is telegraphic in places ("Untrusted guidance from a public registry") and the sentence boundaries are loose, costing some readability.

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, and the description compensates by describing the return contents in detail, including the route template, its parameter values, and excluded pages. Combined with the size hint and the report-link follow-up, an agent has everything needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: it explains that goal drives route selection and is never persisted, which clarifies why the field exists and reinforces the no-personal-details constraint. The detail enum's default and size implications are only partly echoed in prose.

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 enumerates exactly what the tool returns: agent accessibility, the best known route as a URL template with parameter formats and known values, other pages, and robots.txt-excluded pages. That is far more specific than the name alone, though it never states a clean verb+resource framing and does not explicitly contrast itself with get_playbook or list_tasks.

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

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

"Use it for things you can't see on the page: deep links, parameter grammars and codes" gives a clear when-to-use condition, and the closing line says to fetch the report link afterwards, which implies an ordering constraint. It stops short of naming when not to use it or pointing to 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 only supply readOnlyHint=false and openWorldHint=true; the description goes further by explaining what the response contains (descriptions, inputs, reliability), that the site may block agents, and that passing `previous` causes a side-effect report recorded like submit_trace — which explains why this read-shaped call is not marked read-only. It also flags the registry content as untrusted prompt-injection surface, a safety trait no annotation conveys.

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 imperative "Check before browsing" front-loads the trigger, and each subsequent sentence carries a distinct instruction (call, pick, follow up, block-handling, prior-outcome reporting, untrusted content). It is slightly dense and runs long, but no sentence is padding.

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 return-value burden and does so — it names the fields returned and the usable/blocked signal. Combined with the workflow handoff to get_playbook and the reporting hook, an agent has everything needed to call it 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?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: `site` is the site you are about to browse, and `previous` carries the outcome of an unreported task and is recorded like submit_trace, which the schema only gestures at. It stops short of explaining what a report_token is or when a report is expected to be sent, leaving a small 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 and resource — it returns the tasks with verified playbooks for a given site, plus whether automated agents may use that site. It is clearly distinguishable from the sibling `get_playbook`, which handles the follow-up step, and from `get_site_map`.

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 says when to call it ("before opening a website for a task"), what to do next ("then call get_playbook with it"), and what not to do (if the site blocks agents, don't attempt the task and give the user a link instead). Alternative routing is fully spelled out.

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 readOnlyHint=false / openWorldHint=true annotations, the description discloses real behavior: a report keeps the playbook working for the next run, and the reply returns the updated success rate. It also discloses server-side redaction of typed values and personal data on receipt and warns against including passwords or payment details — exactly the kind of context annotations cannot carry.

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 core action, then the two call shapes, then behavior and a safety note — a sensible order with little filler. The wording is dense but each sentence carries distinct information; the parenthetical token-source parentheses are 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 15-parameter mutation tool with no output schema, the description covers the primary invocation paths, the effect on the playbook, and what the reply contains, plus a safety constraint. The main residual gap is guidance on the optional telemetry fields, but an agent can submit correctly without them given the two documented shapes.

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

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

With 15 parameters and only 60% schema coverage, the schema alone cannot tell an agent which fields belong together. The description supplies that grouping — {report_token, success} versus {site, task, playbook_id, outcome} — which is genuine semantic value the schema (zero required fields) does not convey. It leaves the telemetry-style fields (duration_ms, token_cost_usd, framework, steps_log, playbook_version) unexplained, keeping it 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?

The description opens with a specific verb and resource: report the outcome of a task run on a website, explicitly covering both the playbook and non-playbook cases. It also names get_playbook as the source of the report_token, giving a rough sense of its place among siblings, though it never states how it differs from tools like list_tasks.

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 context is clear: call it after completing a task, and pick the short form when you have a report_token or the full form when you don't. It stops short of stating when not to submit a report (e.g., aborted runs or purely local work), so it lacks explicit exclusions.

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