List All Time And Material Entry Matching The Search Keyword

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

The description claims both a list behavior and a create behavior, which is internally inconsistent. Annotations show readOnlyHint=false, which allows write operations, so the creation part is not contradictory with annotations, but the mix of list and create misrepresents the tool's actual behavior. The description does not disclose side effects, such as whether the search operation modifies any data. Without output schema, the description should clarify what the response contains, but it only mentions 'returns the created object' which further confuses.

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 contains four sentences, but one is a contradictory creation statement that should not be there. It also includes extraneous information like 'Procore API: Project Management > Field Productivity' and the full endpoint URL, which are not essential for an AI agent to understand the tool's purpose or usage. The description is not concise and includes misleading content.

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?

The tool has no output schema, so the description should describe the return format, but it does not. It mentions 'returns the created object on success (HTTP 201)' which is inconsistent with a list operation. The description fails to clarify the actual response structure for a search. Given the conflicting statements, the description is incomplete and would confuse an agent trying to use the 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 input schema has two parameters with descriptions that already explain their roles. The description adds that project_id is required and mentions the endpoint, but does not provide additional semantic meaning beyond what the schema already offers. Since schema description coverage is 100%, the baseline is 3, and the description does not significantly enhance understanding of the parameters.

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 starts by stating 'Return a list of all Time And Material Entry matching the search keyword,' which clearly indicates a list operation. However, it then contradicts itself by saying 'Creates a new Field Productivity records and returns the created object on success (HTTP 201).' This muddles the purpose and makes it unclear whether the tool lists or creates. Additionally, there is a sibling tool 'list_all_time_and_material_entry' that likely performs a similar list without search, but the description does not differentiate this tool from that one.

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 says 'Use this to perform the list all action on Field Productivity records' and notes that project_id is required. It provides minimal guidance on context or when to use this tool over alternatives. The contradictory creation statement further confuses usage, as it is unclear if the tool should be used for listing or creating. No mention of when not to use the tool or how it differs from siblings like 'list_all_time_and_material_entry'.

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