Jobsite Safety Reference (free)

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so the description only needs to add context — and it does: the ~300-talk corpus size, bilingual availability, and that it returns the best match plus up to five other matching titles. It omits failure behavior (no match found) and whether results are cached or scoped, keeping it below 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?

Three tight sentences: what you get, how to retrieve it, and what comes back. The output payload is front-loaded and no sentence is 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 carries return-value duty and does it well by listing the returned fields and the best-match-plus-five behavior. The only gap is undefined behavior when nothing matches.

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 schema already supplies examples for topic, the en/es enum, and the note that talk_number comes from other_matches. The description's plain-word examples ('trenching', 'heat', 'ladder setup') largely restate the schema, so it adds little beyond the baseline.

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 ('ready-to-deliver construction toolbox talk from Jobsite's library of nearly 300 talks'), enumerates the payload (title, talking points, discussion question, duration, OSHA standards), and is unmistakable against siblings like search_articles or osha_recordability_check.

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 how to find a talk: by topic or hazard in plain words, by standard number, or by talk_number. That is clear selection guidance, but it never names an alternative tool or a case where you should not use this one.

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, closed-world behavior, so the bar is lower; the description still adds real context: results come from a curated guide, and any section flagged todo:true means the topic is in-scope but undocumented, with an instruction to say so rather than fabricate. That is exactly the kind of behavioral detail an agent needs to avoid hallucinated answers.

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 purpose, then usage triggers, then exclusions, then the todo caveat – a logical order with no filler. It runs slightly long with enumerated NOT clauses, but each sentence carries actionable 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?

For a two-parameter read-only search tool with no output schema, this covers scope, exclusions, result provenance, and the critical todo-flag caveat. An agent has everything needed to call it correctly and interpret an under-documented 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% and the query parameter already carries natural-language examples; the description adds no additional syntax, format, or limit guidance beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

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 ('look up how Jobsite works') and enumerates the topic surface (features, UI navigation, terminology, billing, groups vs crews). An agent can distinguish it from all 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 explicit trigger phrasing ('how do I…', 'where do I find…', 'what does X mean'), plus explicit exclusions routing OSHA/regulatory questions to search_law_corpus or search_training_source and tenant data to list_workers/list_expiring_certs. Nothing 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?

Annotations already declare readOnly/idempotent/non-destructive; the description adds that results are deterministic, that it returns the proposed 300-log classification plus verbatim 1904 rationale and an 8/24-hour reporting deadline, and that unknowns surface as questions rather than guesses. 'Reads and writes no records' is consistent with readOnlyHint=true.

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 dense sentences: what it does, what it returns, how to fill inputs, and the side-effect guarantee. Nothing is padded and the core purpose is front-loaded.

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 carries return-value disclosure — and it does: classification or outstanding questions, rationale with verbatim quotes, and a reporting deadline. Combined with the schema's per-parameter descriptions, an agent has what it needs to call this 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 82%, so the schema already carries most semantics. The description adds meaningful invocation guidance for 11 optional params: omit what isn't known, since unknowns are handled as follow-up questions. It doesn't explain individual fields beyond what the schema does.

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 ('Runs ... decision tree') on a specific resource (OSHA 29 CFR 1904 recordability) and names its output. It is clearly distinct from siblings like search_law_corpus or lookup_jobsite_docs: this is a deterministic evaluator, not a search.

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 input-mapping guidance ('Map the story to the answers; leave out anything not known — unknowns come back as questions, never guesses'), which tells the agent how to call it. It doesn't name an alternative tool or a when-not-to-use condition, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered without the description. The description adds genuine value beyond that by disclosing the return shape (matching articles with a relevant excerpt plus a link) and the no-result behavior. A 3 reflects that these are useful additions layered on an already complete annotation set, not a substitute for 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?

Front-loaded with the resource and content types, then usage triggers, then exclusions, then fallback — a well-ordered structure with no filler sentences. It loses a point for mild redundancy: the competitor comparison examples ('Jobsite vs Procore', 'Jobsite vs SiteDocs', 'Jobsite vs SafetyCulture') are enumerated twice in successive sentences.

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 two-parameter search tool with no output schema, the description covers everything an agent needs: what corpus is searched, what triggers it, what a result contains (excerpt + link), which sibling handles each adjacent intent, and what to do on empty results. No material gap remains.

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 both parameters are documented with examples, making 3 the baseline. The description goes slightly beyond by mapping query intent categories to content categories (competitor-comparison phrasing vs. topical article requests), which tells the agent what kind of query string will retrieve which corpus. It does not add anything about the limit parameter, keeping it out of 5 territory.

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 (search) and resource (Jobsite's published marketing content) and then enumerates the content types covered — blog articles, competitor comparison pages, pillar guides. It explicitly separates itself from lookup_jobsite_docs (product how-to) and search_training_source (OSHA regulatory), so an agent can route without opening sibling schemas.

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 conditions ('how are you better than Procore', 'Jobsite vs SafetyCulture', 'confined space article') and names the two alternative tools with the domains they own instead. It also specifies the negative path — if nothing matches, say so rather than invent a comparison — which is exactly the guardrail an agent needs for a marketing-content search.

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 read-only, idempotent, and closed-world status, and the description adds substantial context beyond them: every match carries an `authority` field with T1/T2/T3 semantics, and it instructs how to characterize each tier. It also discloses the corpus boundary (topics Jobsite trains on, not all of 29 CFR), which is precisely the kind of behavioral constraint 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?

Front-loaded with purpose and scope before alternatives and caveats, and the tier-caution and corpus-boundary sentences earn their place. It is dense and slightly overstuffed with emphasis markers, but no sentence is 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?

No output schema exists, yet the description covers the return shape (per-section text with citation heading and jurisdiction, plus the `authority` tier field), the result cap via schema, and the empty-result semantics. Nothing an agent needs to call or interpret this tool correctly is missing.

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 query, limit, and jurisdiction are already documented, and the description does not add syntax or format detail beyond mentioning jurisdiction implicitly via citation headings. Baseline 3 is appropriate where the schema does the heavy lifting.

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 a verbatim authority corpus) and enumerates the exact contents: 29 CFR per-section text, CA/WA/OR heat and wildfire-smoke rules, OSHA interpretations, NIOSH/CDC/EPA guidance. It explicitly distinguishes itself from search_training_source, so an agent can route without opening either 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 a concrete use condition ('when the user asks what an authority ACTUALLY SAYS', exact rule language, trigger heights, employer duties) and names the alternative tool plus the condition that selects it. It also supplies a negative rule for interpreting empty results ('not in the corpus', never 'no such rule exists').

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, open-world, non-destructive, so the safety profile is covered. The description still adds real value by disclosing the return shape (titles, agencies, dates, URLs, summaries) and the pass-through/no-persistence behavior, which is a meaningful guarantee beyond the annotations. Rate limits and pagination behavior are not mentioned, keeping it below 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?

A single dense paragraph that leads with what the tool does and ends with the exclusions, so it is front-loaded and every sentence carries routing or query-shaping value. It is on the long side for a two-parameter tool, but nothing is 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?

There is no output schema, and the description compensates by enumerating returned fields. Combined with sources, query guidance, and exclusions, an agent can call this correctly with no further information.

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 both parameters are documented in structured data and baseline is 3. The description goes beyond that by giving query-construction guidance ('prefer specific multi-word queries built around an OSHA topic or standard') with worked examples, which meaningfully improves result quality and is not in 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?

States a specific verb (search) and resource (regulatory/safety news) and names the two concrete sources it draws from (Federal Register filtered to OSHA, OSHA news RSS). This is distinguishable from siblings like search_law_corpus or lookup_jobsite_docs at a glance.

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 ('any silica updates this year'), names an explicit alternative (search_training_source for established standards), and lists exclusions (NOT for tenant-data, NOT for general OSHA reference). The agent has everything it needs to route correctly.

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: it discloses the one-time claim link, the 7-day expiry, deletion of unclaimed workspaces, the 3-per-day-per-network rate limit, that no personal details are taken, and the free-vs-paid boundary. These are exactly the operative facts an agent needs before calling a non-idempotent creation tool.

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 core action and the return value are front-loaded, and every clause (expiry, deletion, pricing, rate limit) carries real information. It's a dense paragraph rather than a scannable list, but nothing is wasted.

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 fully carries the return contract (a claim link plus what opening it does) and adds the lifecycle and rate-limit constraints. Nothing an agent needs in order to call it correctly is missing.

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 each parameter's schema description already covers defaults, enum meaning and the length cap. The description only restates that the three parameters are optional, adding no new semantics, 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 ('Create a new Jobsite workspace') plus the defining scope constraint ('holds only sample data ... nothing real'). No sibling tool does anything similar, so an agent can select this unambiguously.

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?

Explains the triggering situation clearly: 'so they can try Jobsite without setting anything up', and adds the free-sample vs paid-real-workers boundary. It doesn't name an alternative tool, but none of the siblings overlaps, so there's little to exclude.

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