DocuGrip

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds real value by disclosing the returned payload (issuing agency source, current edition, date older editions are rejected, plus a browser fill-and-sign page). With no output schema, this return-value detail is exactly the burden the description must carry. Missing only operational caveats such as coverage limits or rate/network behavior.

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 verb and scope, and the usage sentence lands at the end. Slightly padded by the six-code example run (W-9, W-4, 1099-NEC, I-130, I-765, N-400), which conveys coverage breadth but is longer than strictly needed.

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 one-parameter lookup tool with a read-only annotation profile and no output schema, the description is nearly complete: it states scope, trigger, and return contents. An agent can call it correctly. Only the absence of any sibling routing hint keeps it short of full marks.

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

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

Schema description coverage is 100% and the single 'query' parameter is already documented with examples ('W-9' or 'green card application'), so the baseline is 3. The description's form-code list reinforces the expected input format but adds no syntax or normalization rules beyond what the schema states.

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 ('Find') plus a precisely scoped resource: official government forms from named jurisdictions with examples (W-9, W-4, 1099-NEC, I-130, I-765, N-400). It also enumerates what the tool returns (issuing agency source, current edition, rejection date for older editions), which distinguishes it instantly from the generic sibling PDF tools like find_pdf_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 trigger condition: 'Use this when a user asks where to get, fill in or sign a form.' That is clear when-to-use guidance, but it never names or excludes an alternative (e.g., the generic find_pdf_tool) so the agent must infer the routing choice on its own.

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 a safe, read-only, idempotent, non-destructive, closed-world operation, so the description's added value is its domain detail: results include the page, the page runs in the browser, the file is never sent to a server, and redaction strips the underlying text and verifies it can't be copied. That is genuinely useful context beyond the annotations, though it describes the returned tools more than the search operation itself.

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 definition is front-loaded with the core purpose before the usage condition, and the query examples are compact and informative. It runs a little long, and the trailing redaction sentence is arguably tangential to a search tool, but 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?

For a one-parameter, read-only lookup with no output schema, the description covers what it returns ("the matching tools, each with its page") and when to invoke it. The absence of explicit routing against sibling discovery tools is the only meaningful 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?

With a single required parameter at 100% schema coverage, the baseline is 3; the description slightly exceeds it by characterizing the input as the user's own words and supplying four concrete query examples ("combine two contracts", "my scan has no searchable text", etc.) that clarify the expected free-text style.

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 names a specific verb ("Find") and a precise resource ("the DocuGrip page that does a PDF or document task"), and makes clear it accepts a natural-language task description and returns matching tools with their pages. It does not, however, differentiate itself from close siblings such as list_pdf_tools or get_pdf_tool, 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?

It gives a clear usage condition — "Use this when the user wants to do the task themselves" — and enumerates the task types that qualify (compress, merge, split, convert, OCR, redact, sign, fill, edit), plus the privacy-driven case where the file must not be uploaded. It stops short of naming an alternative tool or a when-not-to-use condition.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds no behavioral context beyond what annotations provide, but it also does not contradict them. Baseline 3 given annotations carry the burden.

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?

Single concise sentence with no waste, front-loading the verb, resource, and key lookup parameter. The example is appended efficiently.

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 lookup with annotations covering safety and no output schema, the description is minimally adequate. It states what the tool does but omits return value expectations, error behavior, and how it relates to sibling lookup tools, leaving some gaps.

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%, but there is only one parameter. The description gives an example value ('merge-pdf') which clarifies the expected id format, adding some value. However, it does not explain whether the id is a slug, UUID, or other identifier, nor what happens if an invalid id is provided.

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 ('Get one DocuGrip tool by its id') and provides a concrete example id, making the purpose unambiguous. However, it does not distinguish itself from the sibling 'find_pdf_tool' or 'list_pdf_tools', which are semantically adjacent and would benefit from explicit 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?

The description provides no guidance on when to use this tool versus alternatives like find_pdf_tool or list_pdf_tools. The example id is helpful but does not constitute usage context or exclusions.

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, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safe-read profile is fully covered. The description adds the shape of the returned data (current price, billing terms, buyer guidance) but says nothing about freshness of pricing, currency handling, or that no arguments are accepted.

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 resource and payload, followed by the usage triggers. Every clause carries information; there is no filler or restatement of the title.

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 parameters, no output schema, and annotations that already cover the safety profile, the only gap an agent must fill is what the tool returns and when to call it — both of which the description supplies explicitly. Nothing operational is missing for a simple zero-argument listing tool.

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, which sets the baseline at 4. The description introduces no parameter concepts that could mislead, and there are no arguments whose semantics need explaining.

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 (List) and resource (DocuGrip plans) and enumerates the content of each entry: price, billing terms, suitability, and purchase location. It is immediately distinguishable from the sibling tools, which all concern PDF forms and tools rather than pricing.

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 explicitly names three triggering user intents: asking what DocuGrip costs, asking whether a task requires payment, and asking which plan fits them. No sibling tool competes for these queries, so no alternative routing is needed.

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 the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false), so the bar is lower. The description adds real value beyond them by disclosing what comes back: the official source, the date it was checked, and a compressor page pre-set to a safe target size — important since no output schema exists.

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 verb and resource, then the trigger condition. Two sentences, no filler. The parenthetical example list is longer than strictly necessary but does useful disambiguation work rather than being decoration.

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 (source, checked date, compressor page). One parameter fully documented. Minor gap: no mention of behavior when a portal is unknown or has no official limit on record.

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. The description earns slightly above baseline by broadening the example set well past the schema's 'IRCC'/'USCIS' to ImmiAccount, CM/ECF, Gmail, Turnitin and Etsy, signaling that non-government consumer services are valid values.

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: 'Look up the official file size limit and accepted format for an upload portal or service.' It clearly distinguishes itself from the pdf-tool siblings by scope (limits/formats rather than tool discovery), though it never names or explicitly contrasts a sibling such as find_official_form, which the example list ('IRCC, USCIS') could otherwise be confused 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?

Explicit trigger given: 'Use this when a user says a portal rejected their file or asks how big a PDF may be.' That is a clear when-to-use condition, but there is no when-not-to-use guidance or named alternative for adjacent cases (e.g. form-finding or actual compression workflows).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety is covered structurally. The description adds meaningful value by disclosing the shape of each returned entry (id, name, one-line summary, page), which matters because there is no output 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?

Two short sentences, front-loaded with the action and the returned fields. The closing 'Use this to see what is available' is mildly redundant with the listing verb but still earns its place as usage signal.

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 zero-parameter, read-only listing tool with no output schema, the description supplies the essential missing piece: what each result contains. Little else an agent needs is 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?

The tool takes zero parameters, so the schema carries no semantic burden and the baseline of 4 applies. Nothing in the description is needed to clarify inputs.

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 every DocuGrip tool that is live') and enumerates the fields returned (id, name, one-line description, page). This clearly separates it from retrieval siblings like get_pdf_tool or find_pdf_tool, though it never names them 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?

'Use this to see what is available' implies a discovery/browse use case, but there are no explicit when-not conditions and no routing to find_pdf_tool or get_pdf_tool. The usage context is implied rather than stated.

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 this is a safe, idempotent, read-only, closed-world operation, so the bar is lower. The description adds genuinely useful behavioral context: it returns ordered steps, a run count, the daily allowance, and a matching plan with price and link — output behavior the annotations do not 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?

The core action is front-loaded in the first clause, followed by the outputs and then the usage trigger. It is somewhat run-on with a long mid-sentence list, but every clause carries distinct information and nothing 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?

With no output schema, the description correctly explains the return values (steps, run count, allowance, plan with price/link), and the single required parameter is fully covered by the schema. It is complete enough for correct invocation; only the absence of an explicit single-task alternative keeps it from a 5.

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?

There is a single parameter at 100% schema coverage, so the schema already documents that 'job' is the whole job in the user's words. The description adds a concrete example ('merge these scans, compress to 4 MB for IRCC and add a password') but no additional format or syntax constraints beyond the schema. 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 ('turn a PDF job with several steps ... into ordered steps, each with the DocuGrip page that does it') plus the secondary outputs (run count, allowance, plan fit). This clearly distinguishes it from sibling lookup tools like find_pdf_tool, get_pdf_tool, and get_plans.

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 states the triggering conditions: 'when the user describes more than one thing to do to their files, a batch of files, or work they do regularly.' That is a clear when-to-use rule, though it never names the alternative (find_pdf_tool) for the single-step case, leaving that inference to the agent.

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